Docs › Alert channels

Alert channels

Every alert (MISSED, FAILED, NO_EVIDENCE, BUDGET_RUN, BUDGET_DAY, RETRY_STORM, DRIFT, STALLED) goes to every channel you configure. Settings are one call; fields you leave out keep their value. Check the result with POST /v1/settings/test-alert, which sends a TEST alert to every configured channel. All of this is also on the dashboard.

E-mail (every plan)

curl -X PUT https://api.runvouch.com/v1/settings -H "X-API-Key: $RUNVOUCH_KEY" -H "Content-Type: application/json" \
  -d '{"alert_email": "[email protected]"}'

Subject [RunVouch] KIND: agent, the message in the body, a link to the dashboard. Signing up sets this to your signup address.

Telegram (every plan)

Create a bot with @BotFather, start a chat with it (or add it to a group), and read the chat id from https://api.telegram.org/bot<token>/getUpdates.

curl -X PUT https://api.runvouch.com/v1/settings -H "X-API-Key: $RUNVOUCH_KEY" -H "Content-Type: application/json" \
  -d '{"telegram_token": "123456:ABC...", "telegram_chat": "-100123456"}'

Slack (every plan)

In Slack: Apps, Incoming Webhooks, add to a channel, copy the URL. It starts with https://hooks.slack.com/services/; other URLs are rejected with 422.

curl -X PUT https://api.runvouch.com/v1/settings -H "X-API-Key: $RUNVOUCH_KEY" -H "Content-Type: application/json" \
  -d '{"slack_webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX"}'

The message has a plain-text fallback plus blocks: a header with kind and agent, two fields (kind, agent), the message, and a link to the dashboard. The weekly cost report goes to the same channel.

Generic webhook (every plan)

curl -X PUT https://api.runvouch.com/v1/settings -H "X-API-Key: $RUNVOUCH_KEY" -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://example.com/hooks/runvouch"}'

One JSON POST per alert:

{"kind":"RETRY_STORM","agent":"repo-janitor","run_id":"9808c5af...","message":"tool 'Bash' called 41x with identical input in one run.","ts":1787673506.3}

The weekly report arrives as {"kind":"WEEKLY_REPORT", ...}. Discord, Mattermost and n8n take this as is.

PagerDuty (Team)

In PagerDuty: Services, your service, Integrations, add "Events API v2", copy the 32-character integration key.

curl -X PUT https://api.runvouch.com/v1/settings -H "X-API-Key: $RUNVOUCH_KEY" -H "Content-Type: application/json" \
  -d '{"pagerduty_routing_key": "R0123456789ABCDEF0123456789ABCDEF"}'

On Free and Solo this call returns 402 with a plain message. Behaviour:

• MISSED, FAILED, STALLED, BUDGET_RUN and BUDGET_DAY trigger an incident (severity error) with dedup_key = runvouch:AGENT:KIND, so a repeat of the same problem lands on the same incident.
• NO_EVIDENCE, RETRY_STORM and DRIFT do not page; they still reach your other channels.
• Acknowledging the alert in RunVouch (POST /v1/alerts/{id}/ack, the dashboard, or the MCP tool) sends a resolve for that dedup key.
• The test alert opens an incident with severity info; ack it in RunVouch to resolve it.

Priority alerts (Solo and Team)

Alerts of the same kind for the same agent are sent at most once per 10 minutes; repeats within that window are stored and shown in the dashboard with delivered = -1, but not re-sent. On Solo and Team, MISSED and FAILED skip that cooldown and are delivered immediately, every time. All other kinds keep the cooldown on every plan.

Test and status

curl -X POST https://api.runvouch.com/v1/settings/test-alert -H "X-API-Key: $RUNVOUCH_KEY"
curl https://api.runvouch.com/v1/me -H "X-API-Key: $RUNVOUCH_KEY"   # "channels": which ones are set

Need a key? Get a free key · Stuck? contact