Skip to content

How Do I Get Slack Alerts When an AI Agent Fails?

Get a Slack alert when an AI agent fails: WaveBrain posts failed actions to a Slack channel on the free plan, or build your own with a webhook or hook.

Reviewed by WaveBrain Operations TeamReviewed 6 min read

The short answer

To get Slack alerts when an AI agent fails, have the agent report each action with a success or failure status and route the failures to a channel. The quickest route is WaveBrain: connect one Slack channel on the free plan and every failed action posts there with the agent, project and a link. For a single script, a Slack incoming webhook or a Claude Code PostToolUseFailure hook also works.

Your publishing agent was supposed to post the weekly newsletter at 9am. At 2pm a reader asks where it is, you open the terminal on the server and find a 401 from the email provider, logged four hours earlier where nobody was looking. The agent did report the failure. It just reported it to a place you never check.

The fix is to send failures somewhere you already look, and for most small teams that place is Slack. Below are three ways to do it, from a hosted option that takes a few minutes to scripts you write and maintain yourself.

How do I get a Slack alert when my AI agent fails?#

You need two things: the agent has to record each action with a status, and something has to forward the failed ones to Slack. WaveBrain does both. Agents log actions to it over MCP or REST with status: "failure" when something goes wrong, and a connected Slack channel receives each failed action as it arrives.

If you only have one script or one Claude Code setup to watch, you can skip the hosted service and post straight to a Slack incoming webhook. Slack's own docs describe an incoming webhook as a URL tied to a single channel that accepts a JSON POST like {"text": "Hello, world."}. That covers alerts, though you lose the history and search that come with a shared log.

What does WaveBrain send to Slack when an action fails?#

A failed action posts to your Slack channel with the agent, the project and a link to the full entry in WaveBrain. The Slack message carries the title, project, type and status, and leaves out the details field on purpose, so longer notes (error output, what the agent tried) stay in the dashboard rather than in a channel that more people can read.

A failure reaches WaveBrain in one of three ways:

  1. The agent calls the log_action MCP tool with status: "failure", for example after an email API returns an error.
  2. A script, cron job or CI step sends "status": "failure" to the REST endpoint at POST https://getwavebrain.com/api/v1/actions.
  3. On Claude Code, the open source WaveBrain plugin listens to the PostToolUseFailure hook, so a failed high-stakes call (a deploy, push, publish or payment) is queued and sent even if the agent forgets to log it.

On the Free plan you get 1 Slack channel with failures only. Pro is coming at $12/month and adds unlimited channels, an "all actions" or "sensitive only" mode (deploys, payments, deletes, config changes, publishes) and filters by project, agent and action type.

How do I set up WaveBrain Slack alerts on the free plan?#

Setup takes about five minutes if your agent is already connected. If it isn't, follow the Setup page first or read how to see what your AI agent did for the bigger picture.

  1. Sign up at getwavebrain.com. The free plan needs no credit card and includes 1,000 actions a month.
  2. Create an API key and connect your agent from the Setup page (Claude Code, Codex, Cursor, Hermes or any MCP client, or REST for scripts).
  3. Open Integrations in the dashboard and click Add to Slack.
  4. Pick the channel, for example #agent-alerts, and approve the Slack permission screen.
  5. Send the test message from the Integrations page and check that it lands.
  6. Trigger a real failure, such as a REST call with "status": "failure", and confirm the alert shows up with a link back to the entry.

One limit matters here. WaveBrain alerts on actions that get reported. If an agent crashes before it logs anything, on a client without hooks, there is no entry and no alert. For cron jobs, wrap the command so the failure branch always sends a log (the REST guide has a cron example).

Can I build failure alerts myself with a Slack incoming webhook?#

Yes. Create a Slack app, turn on incoming webhooks, pick a channel and Slack gives you a URL that accepts a JSON POST. Any script can call it when a step fails:

#!/usr/bin/env bash
# run-agent.sh: run a job and alert Slack if it exits non-zero
if ! python3 publish_newsletter.py; then
  curl -s -X POST "$SLACK_WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d '{"text": "publish_newsletter.py failed on '"$(hostname)"'"}'
fi

Slack's docs warn that the webhook URL contains a secret and that Slack actively searches for and revokes leaked ones, so keep it in an environment variable and out of your repo. Each webhook posts to one channel, so a second channel means a second webhook.

This works well for one job on one machine. It gets harder to manage once you have five agents on three machines, because every alert is a separate script, there is no record of the successful runs and nothing links an alert to the work around it.

How do I alert on Claude Code tool failures with a hook?#

Claude Code has a PostToolUseFailure hook event that, per the Claude Code hooks reference, runs when a tool that started executing fails (the tool threw an error, or an MCP tool returned an error result). The docs name sending alerts as one of its uses. A separate StopFailure event runs when a turn ends because of an API error such as a rate limit.

The hook receives JSON on stdin with tool_name, tool_input and an error string. Add it to ~/.claude/settings.json to cover all your projects:

{
  "hooks": {
    "PostToolUseFailure": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/slack-on-failure.sh" }
        ]
      }
    ]
  }
}
#!/usr/bin/env bash
# ~/.claude/hooks/slack-on-failure.sh
input=$(cat)
msg=$(echo "$input" | jq -r '"Claude Code: \(.tool_name) failed: \(.error | .[0:200])"')
jq -n --arg t "$msg" '{text: $t}' | curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" -d @-

Be careful with that error text. It can include file paths, command output or tokens, and Slack is a shared space. Trim it, as above, or send only the tool name. Also expect noise, since a failing grep or a test run that Claude fixes a minute later both count as failures.

Which option should I pick?#

Pick by how many agents you run and whether you also want a record of what succeeded. A webhook script is fine for one job. A Claude Code hook is fine for one person on one laptop. Once several agents on different machines need watching, a shared log with Slack alerts saves you from maintaining a script per agent.

OptionBest forSetupWhat you get in SlackHistory of successful actions
WaveBrain Slack alertsSeveral agents and machinesConnect agent, click Add to SlackTitle, project, type, status, link to entryYes, searchable timeline
Slack incoming webhook in a scriptOne cron job or scriptCreate a Slack app and webhookWhatever text you sendNo
Claude Code PostToolUseFailure hookOne Claude Code userHook in settings.json plus a scriptWhatever text you sendNo

WaveBrain is an activity log, so it won't page you about model latency, token spend or prompt errors inside an app you build. LLM tracing tools cover that. It reports what your agents did and which of those actions failed.

If you want failed agent actions in Slack without writing a script per agent, try WaveBrain free. The free plan includes 1,000 actions a month and one Slack channel for failures.

Frequently asked questions#

Can I get Slack alerts for every action, not only failures?#

On WaveBrain's free plan the Slack channel receives failures only. Pro, which is coming, adds an "all actions" mode, a "sensitive only" mode and filters by project, agent and type.

Does WaveBrain send the full error details to Slack?#

No. Slack messages carry the title, project, type and status plus a link, and leave out the details field so longer notes stay in the dashboard.

Will I get an alert if my agent crashes without logging anything?#

Not from WaveBrain, because it alerts on actions that were reported. Use hooks where your client supports them, or wrap scripts so the failure branch always logs.

How many Slack channels can a webhook post to?#

One. Slack's docs describe each incoming webhook URL as specific to a single channel, so each extra channel needs its own webhook.

Does Claude Code have a built-in hook for failed tool calls?#

Yes. The PostToolUseFailure event runs when a tool fails, and StopFailure runs when a turn ends because of an API error.

Sources#