Notification Hooks: Custom Alerts from Claude Code

You’re running a long-running task—maybe it’s a test suite that takes twenty minutes to execute, or Claude is generating a complex report across hundreds of files. You don’t want to stare at the screen the whole time, but you also don’t want to miss the moment it finishes. That’s where notification hooks come in.

Notification hooks are Claude Code’s way of broadcasting events to wherever you want them to go: Slack, email, Discord, PagerDuty, or custom webhooks. Instead of checking back manually, notifications come to you. And because they’re hooks, you can filter them, route them intelligently, and route events based on severity—so you’re not drowning in alerts about routine operations, only the ones that matter.

This article shows you how to set up notification hooks, route them to Slack and webhooks, filter by severity, and build a custom dashboard to track Claude’s activity. We’ll walk through real examples you can use immediately, including edge cases and troubleshooting patterns you’ll actually encounter in production. The ultimate goal is making Claude Code visible and manageable in your workflow, not something you have to babysit.

Why Notifications Matter in AI Workflows

When Claude Code runs autonomous tasks—especially long-running ones—visibility is critical. Without notifications, you’re flying blind. You might miss important events that require attention.

You might miss:

• Task completion: Did that bulk edit finish, or is it still running? How long until you can use the results?
• Failures: Why did that validation fail? Is it a real problem or a transient error?
• Rate limits: Is Claude hitting API limits and backing off? Should you retry or wait?
• Resource usage: How much compute did that operation consume? Are you approaching quota limits?
• Anomalies: Did something behave unexpectedly? Did a tool take 10x longer than usual?

Manually checking status means inefficient waiting. You either interrupt your work constantly to check progress (which destroys focus), or you forget about the task entirely and discover failures hours later (which creates emergency situations). Neither option is ideal. Notifications give you the third option: you stay informed automatically without managing anything. Claude Code handles the monitoring. You get pinged when action is needed.

This isn’t just convenience. It’s about operational confidence and team velocity. When you know Claude’s working and when it completes, you can plan your day around it. You can schedule other work. You can take a break knowing you’ll be notified the moment something needs attention. Contrast that with constantly checking a progress bar or reviewing logs repeatedly. The psychological impact of working with notifications versus without them is significant. Notifications reduce cognitive load and free mental energy for actual problem-solving.

Consider a team using Claude Code for large batch operations. Without notifications, someone has to manually babysit each operation. With notifications, each team member can work independently and get pinged only when their attention is needed. That’s a massive difference in team productivity. A development team running large refactoring operations can schedule them and move on, knowing they’ll be alerted when complete. A data engineering team can run batch transformations overnight and be notified in the morning whether they succeeded or failed, without anyone having to check status manually.

The quality of your notifications also matters deeply. A poorly designed notification system floods you with noise. You get alerted for every routine success, every minor hiccup, every progress update. Your team turns off notifications because there’s too much signal-to-noise ratio. Now you’re worse off than before—you have a system that can alert you, but nobody listens because the alerts stopped meaning anything. The art of good notifications is making sure every alert is worth someone’s attention.

Types of Notification Events and Severity Levels

Not all events deserve notifications. Some are routine noise. Others are critical and need immediate attention. Your notification strategy should match event severity to notification urgency. This is about signal-to-noise ratio. The goal is ensuring that when a notification arrives, it means something.

Critical events (notify immediately, wake someone up at 3 AM if necessary):

• Process crashes with an error that requires human intervention
• API authentication failure that blocks all operations
• Resource exhaustion (out of memory, disk full)
• Security anomalies detected
• SLA violations (operation took 10x longer than expected)

Critical events need immediate attention. They represent system failures that could compound if ignored. An authentication failure might be a one-time network hiccup, or it might be a credential that’s been compromised. You need to know immediately so you can investigate and take action. If a security anomaly is detected, you want to know right now, not hours later when reviewing logs. These are wake-up-at-3-AM events. They’re rare, but when they happen, they need attention.

High-priority events (notify within minutes, escalate if ignored):

• Tool failures that affect multiple downstream tasks
• Unusual error rates (5x normal baseline)
• Cost anomalies (token burn rate 10x forecast)
• Completion of long-running critical operations (so user can take next step)

High-priority events indicate something isn’t working as expected, but it’s not an immediate catastrophe. A tool failed—maybe it’ll succeed on retry, or maybe you need to investigate. Error rates spiked—you should look into it but it might resolve itself. A critical operation completed—this is time-sensitive because the next step in your pipeline depends on it.

Medium events (log and digest, notify during work hours):

• Individual tool timeouts that succeeded on retry
• Transient network errors that resolved on retry
• Completion of routine operations (informational, not urgent)
• Performance degradation (slower than usual but still working)

Medium events are informational. They might warrant investigation later, but they don’t need immediate interruption. A tool timing out once and succeeding on retry is normal behavior. Transient network errors are expected in distributed systems. A routine operation completing is worth knowing about, but it’s not urgent. These are the notifications you might batch up and review during a morning coffee break.

Low-priority events (log but don’t notify):

• Routine successes (unless specifically requested)
• Retries that succeed (noise after the first attempt)
• Cache hits (good for performance, not interesting to operators)
• Progress updates on long operations (too frequent to be useful)

Low-priority events should almost never interrupt you. They’re useful for auditing and debugging, so they should be logged, but they shouldn’t generate notifications. When Claude Code successfully executes a task, that’s expected behavior. When a cache hits, that’s optimization working correctly. When an operation retries and succeeds, that’s fault tolerance working as designed. None of these warrant a notification.

This tiered approach prevents notification fatigue. Your team doesn’t turn off alerts because there are too many. They trust that alerts mean something needs attention. That trust is precious. Guard it carefully. The moment your team starts ignoring notifications because they’re too frequent, you’ve failed. Every notification must earn its place in their awareness.

The threshold between categories is different for different teams. A startup might notify about every completed operation (high signal-to-noise, but you care about everything). A large company might only notify about critical failures (low signal-to-noise, but notifications are actually important). Calibrate your thresholds for your organization. Then monitor whether teams are turning off notifications. If they are, your thresholds are too aggressive—you’re alerting about things that don’t matter, polluting the signal.

Setting Up Slack Notifications

Slack is the most common notification destination because it’s already in your communication workflow. Here’s how to wire it up properly with resilience and good formatting:

// hooks/notifications/slack.mjs


export class SlackNotifier {
  constructor(webhookUrl) {
    this.webhookUrl = webhookUrl;
    this.retries = 3;
  }

  async send(event) {
    const message = this.buildMessage(event);

    for (let i = 0; i < this.retries; i++) {
      try {
        const response = await fetch(this.webhookUrl, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(message),
        });

        if (response.ok) return { success: true };

        if (response.status === 429) {
          // Rate limited, back off
          await new Promise((r) => setTimeout(r, 2 ** i * 1000));
          continue;
        }
      } catch (error) {
        console.error("Slack notification failed:", error);
        if (i < this.retries - 1) {
          await new Promise((r) => setTimeout(r, 1000 * (i + 1)));
        }
      }
    }

    return { success: false, error: "Failed to send after retries" };
  }

  buildMessage(event) {
    const color =
      event.severity === "critical"
        ? "danger"
        : event.severity === "high"
          ? "warning"
          : "good";

    return {
      attachments: [
        {
          color,
          title: event.title,
          text: event.message,
          fields: [
            { title: "Status", value: event.status, short: true },
            { title: "Severity", value: event.severity, short: true },
            {
              title: "Timestamp",
              value: new Date().toISOString(),
              short: false,
            },
          ],
          footer: "Claude Code Notifications",
          ts: Math.floor(Date.now() / 1000),
        },
      ],
    };
  }
}

The webhook URL comes from Slack’s incoming webhooks feature. Create one in your workspace settings, get the URL, and store it as an environment variable. Never commit webhook URLs to git—they’re as powerful as passwords. Once the notifier is set up, sending a notification is a single function call. The retry logic here is important. Slack’s rate limits are generous, but network hiccups happen. Exponential backoff (1 second, then 2, then 4) gives Slack time to recover without hammering it. After three attempts spanning roughly 7 seconds, you accept failure and log it. You don’t retry forever—that’s wasteful and can create thundering herd problems.

The message format uses Slack’s attachment syntax for rich formatting. Colors signal severity at a glance. Red attachments grab attention immediately. Green signals normalcy. The timestamp field helps when you’re reviewing alerts hours later—you can see exactly when things happened and correlate with other events. This contextual information is invaluable for understanding incident timelines.

When you build Slack messages, remember that color coding is cultural. Your team might interpret colors differently depending on their background. Pair colors with explicit severity labels so there’s no ambiguity. The message should also include a clear call-to-action when appropriate. “Click here to review the failed operation.” “Run this command to investigate.” “Contact #oncall for immediate assistance.” Make it obvious what the recipient should do next.

Email Notifications for Critical Events

Slack is great for real-time notifications while you’re working, but email is better for critical events that might require action even after hours. Email creates a permanent record, searchable and archivable. You’ve got a paper trail for compliance purposes. Email is more reliable than Slack for truly critical events—a message might get lost in the Slack notification stream, but email sits in your inbox demanding attention.

// hooks/notifications/email.mjs


export class EmailNotifier {
  constructor(config) {
    this.transporter = nodemailer.createTransport(config);
    this.from = config.from || "[email protected]";
  }

  async send(event) {
    const html = this.buildHtml(event);

    return this.transporter.sendMail({
      from: this.from,
      to: event.recipients,
      subject: `[${event.severity.toUpperCase()}] ${event.title}`,
      html,
      text: event.message,
    });
  }

  buildHtml(event) {
    return `
      <h2>${event.title}</h2>
      <p><strong>Severity:</strong> ${event.severity}</p>
      <p><strong>Status:</strong> ${event.status}</p>
      <p><strong>Time:</strong> ${new Date().toISOString()}</p>
      <hr>
      <p>${event.message}</p>
      ${event.details ? `<pre>${event.details}</pre>` : ""}
    `;
  }
}

Email is less exciting than Slack (no pretty formatting, slower delivery), but it’s reliable and universal. Every engineer has email. Not everyone has Slack open at 3 AM when an incident happens. Critical alerts should go to email. Urgent alerts can go to both, hitting multiple notification channels to increase the chance someone sees it immediately.

Email also creates a permanent record for compliance and auditing. If you’re in a regulated industry, you probably need to show that critical events were notified and tracked. Email provides that audit trail naturally. Slack messages eventually disappear (if you’re not on the paid plan) or get lost in the noise. Email stays in inboxes indefinitely unless explicitly deleted. This persistence is a feature for compliance purposes.

Custom Webhook Notifications

Sometimes you want to pipe notifications to your own system: a monitoring dashboard, an incident management tool, or a custom database. Webhooks let you do that without being locked into specific platforms.

// hooks/notifications/webhook.mjs
export class WebhookNotifier {
  constructor(url, authToken) {
    this.url = url;
    this.authToken = authToken;
  }

  async send(event) {
    const payload = {
      event: event.type,
      severity: event.severity,
      title: event.title,
      message: event.message,
      timestamp: Date.now(),
      metadata: event.metadata || {},
    };

    try {
      const response = await fetch(this.url, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${this.authToken}`,
        },
        body: JSON.stringify(payload),
      });

      return { success: response.ok, status: response.status };
    } catch (error) {
      console.error("Webhook notification failed:", error);
      return { success: false, error: error.message };
    }
  }
}

Webhooks let you build custom automation. Receive a notification about a failed tool, automatically create a Jira ticket with context. Receive a completion notification, trigger a deployment. The possibilities are endless. Your webhook receiver can do whatever you want with the data—update dashboards, trigger further automation, feed into analytics systems. You’re not limited to Slack or email anymore; you can integrate with literally any system that accepts HTTP requests.

The webhook approach is also extensible. You can chain webhooks—one webhook triggers another, creating cascading effects. A failed critical operation might trigger a webhook that creates an incident, escalates to the oncall engineer, notifies Slack, creates a Jira ticket, and records the event in your observability platform. All from a single notification event. This is where notification systems become powerful—they’re the glue that coordinates multiple systems in response to events.

Building a Notification Filter

Not every event needs to notify everyone. You might want different teams notified for different events. Notification filters prevent alert fatigue by being selective about what actually generates notifications.

// hooks/notifications/filter.mjs
export class NotificationFilter {
  constructor(rules = []) {
    this.rules = rules;
  }

  shouldNotify(event) {
    // Default: notify critical events, ignore low-priority
    if (event.severity === "critical") return true;
    if (event.severity === "low") return false;

    // Apply custom rules
    for (const rule of this.rules) {
      if (this.matchesRule(event, rule)) {
        return rule.notify;
      }
    }

    // Default: notify medium and high
    return ["medium", "high"].includes(event.severity);
  }

  matchesRule(event, rule) {
    if (rule.type && event.type !== rule.type) return false;
    if (rule.tool && event.tool !== rule.tool) return false;
    if (rule.status && event.status !== rule.status) return false;
    return true;
  }

  getRecipients(event) {
    // Route to appropriate channels
    if (event.severity === "critical") {
      return ["#oncall", "#engineering-leads"];
    }
    if (event.type === "deployment") {
      return ["#deployments"];
    }
    if (event.type === "performance") {
      return ["#performance-alerts"];
    }
    return ["#claude-code-updates"];
  }
}

Filtering prevents alert fatigue. Your team doesn’t turn off notifications when there are too many. Instead, you be selective about what notifies. The filter is your gatekeeper. Rule-based routing is powerful. As your system grows, you’ll want different alerts to go to different places. Infrastructure alerts go to the infrastructure team. Feature-related alerts go to product. Performance alerts go to performance specialists. One event can trigger multiple notifications to different recipients based on its characteristics. This routing intelligence ensures the right information reaches the right people without overwhelming anyone.

Creating a Comprehensive Alert Hook

Now let’s tie everything together in a hook that handles notifications end-to-end. This is the orchestration layer that coordinates all the notification channels.

// hooks/post-execution.mjs





const slackNotifier = new SlackNotifier(process.env.SLACK_WEBHOOK_URL);
const emailNotifier = new EmailNotifier({
  service: "gmail",
  auth: {
    user: process.env.EMAIL_USER,
    pass: process.env.EMAIL_PASSWORD,
  },
});
const webhookNotifier = new WebhookNotifier(
  process.env.WEBHOOK_URL,
  process.env.WEBHOOK_AUTH_TOKEN,
);

const filter = new NotificationFilter([
  { type: "error", notify: true }, // Always notify errors
  { type: "progress", notify: false }, // Never notify progress
]);

export async function onPostExecution(context) {
  const { result, error } = context;

  const event = {
    type: error ? "error" : "success",
    severity: error ? "high" : "low",
    title: error ? `Tool failed: ${error.message}` : "Task completed",
    message: error?.stack || result.summary,
    status: error ? "failed" : "completed",
    tool: context.toolName,
    timestamp: new Date().toISOString(),
  };

  if (!filter.shouldNotify(event)) return;

  // Send to appropriate channels
  await slackNotifier.send(event);

  if (event.severity === "critical") {
    await emailNotifier.send({
      ...event,
      recipients: ["[email protected]"],
    });
  }

  await webhookNotifier.send(event);
}

This hook runs after every tool execution. It builds an event object describing what happened, checks if it should notify based on rules, then sends notifications to all configured channels. Each notifier handles its own retry logic, formatting, and delivery. The separation of concerns is important. Each notifier knows how to format messages for its platform. Slack knows how to build rich attachments with colors and fields. Email knows how to send properly-formatted HTML. Webhooks know to serialize clean JSON. The hook orchestrates without caring about implementation details. This architectural separation means you can swap out notification channels easily. Need to add PagerDuty support? Create a PagerDutyNotifier class and wire it in. Need to stop using email? Remove the email notifier. The orchestration layer stays clean because each piece has a single responsibility.

Monitoring Notification Delivery

Notifications aren’t useful if they don’t arrive. You need visibility into whether they’re being delivered successfully. This monitoring-of-the-monitor is essential for production systems.

// hooks/notifications/monitoring.mjs
export class NotificationMonitor {
  constructor() {
    this.sent = [];
    this.failed = [];
  }

  recordSent(event, notifier) {
    this.sent.push({
      timestamp: Date.now(),
      event: event.type,
      notifier,
      severity: event.severity,
    });
  }

  recordFailed(event, notifier, error) {
    this.failed.push({
      timestamp: Date.now(),
      event: event.type,
      notifier,
      error: error.message,
      severity: event.severity,
    });
  }

  getSummary() {
    return {
      totalSent: this.sent.length,
      totalFailed: this.failed.length,
      failureRate: this.failed.length / (this.sent.length + this.failed.length),
      recentFailures: this.failed.slice(-10),
    };
  }
}

Track notification delivery success and failure. If Slack’s webhook is down, you want to know that. If email delivery fails repeatedly, that’s a production issue. Monitor your monitors. This meta-monitoring catches when your notification system itself breaks, preventing a situation where you’re silently missing alerts because the alerting system is broken.

Handling Notification Edge Cases

Real-world notification systems encounter edge cases. Here’s how to handle them gracefully without creating worse problems:

Duplicate notifications: If the same tool fails multiple times in quick succession, you might get spammed. Deduplicate within a time window so you’re not overwhelmed:

const DEDUP_WINDOW = 60000; // 1 minute
const recentNotifications = new Map();

function isDuplicate(event) {
  const key = `${event.type}-${event.tool}`;
  const lastNotified = recentNotifications.get(key);

  if (lastNotified && Date.now() - lastNotified < DEDUP_WINDOW) {
    return true;
  }

  recentNotifications.set(key, Date.now());
  return false;
}

Notification ordering: If multiple events happen simultaneously, you want them ordered clearly so you can correlate them properly. Use timestamps and batch:

const notificationQueue = [];

function queueNotification(event) {
  notificationQueue.push({ ...event, queued: Date.now() });
  notificationQueue.sort((a, b) => a.timestamp - b.timestamp);
}

async function flushQueue() {
  while (notificationQueue.length > 0) {
    const event = notificationQueue.shift();
    await sendNotification(event);
  }
}

Rate limit handling: Slack rate limits are generous but real. Respect them by throttling:

class RateLimitedNotifier {
  constructor(baseNotifier, minDelayMs = 1000) {
    this.baseNotifier = baseNotifier;
    this.minDelayMs = minDelayMs;
    this.lastNotificationTime = 0;
  }

  async send(event) {
    const timeSinceLastNotification = Date.now() - this.lastNotificationTime;
    if (timeSinceLastNotification < this.minDelayMs) {
      await new Promise((r) =>
        setTimeout(r, this.minDelayMs - timeSinceLastNotification),
      );
    }

    this.lastNotificationTime = Date.now();
    return this.baseNotifier.send(event);
  }
}

These patterns handle real-world complexity. Deduplication prevents notification spam. Queuing ensures order. Rate limiting respects API limits. Your notification system becomes robust and production-ready.

Dashboard: Tracking Notification Activity

Beyond sending notifications, you want visibility into what’s happening. A simple dashboard shows notification metrics and health. This isn’t just for curiosity—dashboards are your early warning system for when the notification system itself breaks:

// dashboard/notifications.mjs


const app = express();
const notificationLog = [];

app.get("/api/notifications/summary", (req, res) => {
  const last24h = notificationLog.filter(
    (n) => Date.now() - n.timestamp < 86400000,
  );

  res.json({
    total: last24h.length,
    byType: groupBy(last24h, "type"),
    bySeverity: groupBy(last24h, "severity"),
    deliveryRate: last24h.filter((n) => n.delivered).length / last24h.length,
  });
});

app.get("/api/notifications/recent", (req, res) => {
  const limit = parseInt(req.query.limit) || 50;
  res.json(notificationLog.slice(-limit).reverse());
});

function groupBy(arr, key) {
  return arr.reduce((acc, item) => {
    acc[item[key]] = (acc[item[key]] || 0) + 1;
    return acc;
  }, {});
}

A dashboard lets you see notification volume, success rates, and recent activity. This visibility helps you tune your notification rules and identify problems with delivery systems. If you see a spike in failed deliveries, you know something’s broken. If you see that certain event types are always ignored by your team, maybe you need to re-tune the severity levels.

The dashboard also becomes a communication tool. You can show stakeholders notification patterns: “Look at this—our system has been running for 72 hours without a single critical alert. Here’s why I’m confident it’s healthy.” Or conversely, “See this spike? That’s when the database connection pool was exhausted. We fixed it with this change, and the alerts stopped.” The data tells a story about your operational health.

Many teams display notification dashboards on public screens in their offices or link them in their Slack channels. The transparency builds organizational confidence. Everyone can see that the system is being monitored, that problems surface immediately, and that there’s a proactive response to issues. That visibility is powerful for team trust and incident response culture. When leadership sees that the system surfaces problems in minutes, not hours, confidence in your operations increases.

Scaling Notifications

As Claude Code usage grows, notification volume increases. You need to scale thoughtfully without creating alert fatigue:

Batching: Instead of sending individual notifications, batch them together:

class BatchedNotifier {
  constructor(baseNotifier, batchSize = 10, batchTimeMs = 5000) {
    this.baseNotifier = baseNotifier;
    this.batch = [];
    this.batchSize = batchSize;
    this.batchTimeMs = batchTimeMs;

    setInterval(() => this.flush(), batchTimeMs);
  }

  async send(event) {
    this.batch.push(event);
    if (this.batch.length >= this.batchSize) {
      await this.flush();
    }
  }

  async flush() {
    if (this.batch.length === 0) return;

    const batchEvent = {
      type: "batch",
      events: this.batch,
      count: this.batch.length,
      timestamp: Date.now(),
    };

    await this.baseNotifier.send(batchEvent);
    this.batch = [];
  }
}

Batching reduces notification frequency while preserving information. Instead of 100 individual alerts, you get 10 batches of 10. Slack doesn’t get hammered. Your team still sees everything that matters.

Sampling: For low-priority events, sample instead of notifying every occurrence:

function shouldSample(event, sampleRate = 0.1) {
  if (event.severity !== "low") return true; // Always include high severity
  return Math.random() < sampleRate;
}

Sampling reduces noise. You still get a statistical picture of what’s happening without being notified about every routine success.

Integration Testing Notifications

Before deploying to production, test your notification system to catch configuration issues early:

// test/notifications.test.mjs


describe("Notifications", () => {
  it("should format critical events as red attachments", () => {
    const notifier = new SlackNotifier("https://automateanddeploy.com:3000/webhook");
    const event = {
      severity: "critical",
      title: "API Down",
      message: "Claude API is unreachable",
      status: "failed",
    };

    const message = notifier.buildMessage(event);
    assert.equal(message.attachments[0].color, "danger");
  });

  it("should retry failed deliveries", async () => {
    const notifier = new SlackNotifier("http://invalid-url");
    const event = { severity: "high", title: "Test", message: "Test" };

    const result = await notifier.send(event);
    assert.equal(result.success, false);
  });
});

Test that messages format correctly, retry logic works, and edge cases are handled. Don’t discover notification bugs in production when you actually need alerts.

The Long View: Notifications as Infrastructure

Notifications might seem like a nice-to-have feature. They’re actually critical infrastructure for operational visibility. When your system works but you don’t know it works, that’s invisible success. When it breaks and you don’t know, that’s invisible failure. Notifications make your system visible.

Over time, notifications become the operational feedback loop. You see patterns: certain operations always take longer on Tuesday mornings. Certain errors happen during deployments. Certain tools fail more often than others. This data informs optimization work. You fix the biggest problems because notification patterns show you what actually matters.

Consider how this plays out in practice. A team without notifications experiences slow feedback loops. A developer runs a critical batch operation at 4 PM, then leaves for the day. At 6 PM, the operation fails silently. Nobody knows. The next morning, they discover 12 hours of data processing never completed. The whole day’s work gets lost. With notifications, they’re alerted within seconds. They can either re-run it or plan around it. The notification catches problems while they’re still fixable.

Notifications also build confidence in your system. When you’re confident your system will alert you to problems, you trust it. You can focus on other work. You’re not constantly second-guessing whether things are okay. That confidence is underrated but powerful. It affects team morale, velocity, and the quality of work produced. Developers spend less mental energy worrying about background processes and more thinking about features, architecture, and solving actual problems.

There’s a psychological element here. A team with automated notifications feels more professional, more in control. They’ve built infrastructure that works with them, not against them. They can scale their operations without scaling headcount because they’ve automated the visibility that used to require constant manual checking. One person can oversee operations that would have required three people checking dashboards manually.

The most successful implementations of notification systems are those that treat them as a living system. You don’t set up notifications once and forget them. You refine them. You change severity thresholds based on what actually matters. You add new notification types as you discover gaps. You deprecate notifications that never fire because the underlying issue was fixed. The notification system becomes a reflection of your operational maturity. It grows with your system.

Troubleshooting Common Notification Issues

Webhooks not firing: Check that webhook URLs are correct and endpoints are receiving requests. Add logging on the receiver side to verify delivery. Many teams discover they’ve gotten the webhook URL wrong, or the receiving server is rejecting requests for authentication reasons. A simple test is to manually curl the endpoint with sample data. If that fails, you’ve found your problem. If it succeeds, the issue is likely with how Claude Code is formatting the request.

Slack rate limiting: You’re sending too many notifications. Implement batching and adjust severity thresholds to reduce volume. The Slack API is generous with rate limits (typically 1 request per second), but when you’re running batch operations that trigger dozens of notifications, you’ll hit it. The solution is batching—collect notifications into groups before sending. Send 10 grouped notifications instead of 100 individual ones.

Email going to spam: Check DKIM, SPF, and DMARC configuration. Email providers are increasingly strict about spam prevention. If you’re sending from a Gmail account or third-party service, set up proper authentication. Many critical alerts end up in spam because the email server wasn’t properly configured. Always check your spam folder if you think notifications aren’t arriving.

Notification storms: If a tool fails repeatedly, you’ll get spammed. Implement deduplication windows and exponential backoff. This is surprisingly common—a database query fails, it retries, it fails again, and you get 20 notifications in a second. The deduplication window says “if we just notified about this type of event from this tool, don’t notify again for 60 seconds.” This prevents alert fatigue while still ensuring critical issues surface.

Silent notification failures: The most insidious problem is when the notification hook fails silently. It tries to send to Slack, Slack is down, the hook catches the error but doesn’t re-report it anywhere, and you think you got notified when you didn’t. The fix is defensive—implement notification delivery retry logic, fallback mechanisms, and always log to a local file as a last resort. Never rely on a single notification channel.

Moving Notifications Into Production: Lessons from the Field

When teams first deploy notification systems at scale, unexpected challenges emerge. One team configured notifications perfectly but then experienced “alert fatigue” within a week—so many notifications were firing that the team stopped paying attention. Another team set up slack notifications but discovered the webhook rate limit was too aggressive, causing legitimate alerts to be silently dropped.

The lesson teams learn is that notification systems require operational care. You need to monitor the monitors. Create metrics about your notification delivery: How many notifications were sent? How many failed? What’s the failure rate by destination? By alert type? This meta-monitoring ensures your notification system itself remains healthy. A broken notification system is worse than no notifications—you’re silently missing alerts while thinking you’re covered.

Many teams also discover they need different notification urgency levels for different audiences. Your VP of Engineering doesn’t need to know about every test failure, but security teams need to know immediately if credential detection blocks something. Your backend team needs to hear about API errors; your frontend team doesn’t. Routing becomes sophisticated—the same event might generate notifications to multiple channels with different urgency levels, or to multiple teams based on ownership boundaries.

The infrastructure underlying notifications also matters more than it initially appears. Slack webhooks go down occasionally. Email delivery can fail silently. Webhooks to custom systems can be unreliable if the receiving system has issues. Smart teams implement fallback mechanisms. If Slack fails, try email. If email fails, try a webhook to a backup system. This layering ensures critical alerts always get through, even if individual channels are unreliable. It’s another example of defense-in-depth—you’re not relying on any single notification channel to be perfect.

Conclusion

Build notifications early. Tune them over time. Make them part of your operational culture. Your future self will thank you when you’re informed automatically instead of discovering problems manually. Notifications transform Claude Code from a tool you have to check on constantly into a background worker that alerts you only when your attention is needed. As your system grows and Claude Code becomes more integral to your workflow, good notification infrastructure becomes non-negotiable. It’s not a luxury—it’s foundational operational capability that scales your team’s ability to manage complexity without linearly scaling headcount.

---

-iNet