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)

Add to Slack installs it in one click when the Slack app is enabled on this server; that page says whether it is. The webhook route below always works. By hand, 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.

Discord (every plan)

In Discord: Server Settings, Integrations, Webhooks, New Webhook, pick the channel, Copy Webhook URL.

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

One embed per alert: kind and agent as the title, the message as the body, red for a failure and green for a test, with a link to the dashboard. Other hosts are rejected with 422.

Microsoft Teams (every plan)

In Teams the modern route is a workflow: in the channel, click the three dots, Workflows, "Post to a channel when a webhook request is received", and copy the URL it gives you (it ends up on logic.azure.com). An old Office 365 connector URL still works too.

curl -X PUT https://api.runvouch.com/v1/settings -H "X-API-Key: $RUNVOUCH_KEY" -H "Content-Type: application/json" \
  -d '{"teams_webhook_url": "https://prod-1.westeurope.logic.azure.com/workflows/…/triggers/manual/paths/invoke?…"}'

The alert arrives as an adaptive card: kind and agent in the heading, the message underneath, a button to the dashboard.

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