Skip to content

Send alerts to Slack

A Slack recipient delivers outage and recovery alerts straight to a Slack channel through a Slack incoming webhook — a destination um-api understands natively, not a generic type: "webhook" recipient pointed at Slack. Never attach a Slack destination to a type: "webhook" recipient. Monitive’s webhook payload isn’t the shape Slack expects, and Slack silently discards it. See Choose who gets alerts for why a native recipient type exists for destinations like this one.

A Slack recipient is active the moment you create it — there’s no confirmation step and no secret to copy, unlike an email recipient or a webhook recipient’s signing secret.

First, get an incoming webhook URL from Slack:

  1. Create a Slack app at api.slack.com/apps (or open one you already have).
  2. Turn on Incoming Webhooks.
  3. Click Add New Webhook to Workspace and pick the channel there.
  4. Copy the generated webhook URL — it looks like https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX.

Treat that URL as a credential. Anyone who has it can post to the channel you picked — don’t commit it, log it, or paste it somewhere public. If one ever leaks, revoke it in Slack’s Incoming Webhooks settings and replace it on the recipient (see Troubleshooting).

Then, in the dashboard:

  1. Go to Recipients and click Create recipient.
  2. Choose the Slack tab, paste the webhook URL, pick which events to notify on, and optionally turn on Default for new monitors.
  3. Click Create recipient. You’ll see a Recipient “…” created. toast, and the dialog closes — the recipient is already active.

The Create recipient dialog with the Slack tab selected and a webhook URL pasted in

  1. Before attaching it anywhere, use the Send test row action on the Recipients page to confirm Slack actually accepts the URL — see Troubleshooting for what a failed test looks like. A real alert sent through a recipient with a revoked or otherwise unusable URL fails immediately with no retry, so don’t attach a recipient whose test hasn’t passed; fix or replace the URL and test again first.
  2. Once the test succeeds, attach it to a monitor from that monitor’s Recipients section, the same way you would any other recipient type — see the alert recipients guide.

Edit a Slack recipient. The Webhook URL field starts blank, with the placeholder Leave blank to keep the current URL and a Current: https://hooks.slack.com/services/T…/B…/******** line underneath showing the masked value um-api stores. Leave the field blank to keep the existing URL, or paste a new one to replace it — pasting the masked value back doesn’t work (see Troubleshooting).

Rotating the URL. Saving a new URL in this field is the cutover, not a staged step — the moment you save, the recipient’s live webhook is the new URL, before Send test has confirmed Slack accepts it. This sequence is not gap-free: a real alert delivered between save and a successful test goes only to the unverified replacement, and once saved, the Current: line only ever shows the masked value — the old URL is unrecoverable from the dashboard. Before you start, copy the current webhook URL somewhere safe; it’s your only way back if the new one fails. Then: create the replacement webhook in Slack, paste it into the recipient, save, and Send test it immediately. If the test fails or is rate-limited (see Plan limits), paste the retained old URL back in and save to restore delivery before troubleshooting further. Only revoke the old webhook in Slack’s Incoming Webhooks settings once the test against the new URL succeeds.

Read the webhook URL with a silent prompt instead of writing it into the command — a URL typed directly into -d lands in your shell history and is visible to other users on the box via ps while curl runs:

Terminal window
read -rsp 'Slack webhook URL: ' SLACK_WEBHOOK_URL; echo
printf '%s' "$SLACK_WEBHOOK_URL" | jq -Rs '{
name: "on-call-slack",
type: "slack",
config: {url: .},
events: ["down", "up", "flapping"]
}' | curl -X POST https://api.monitive.com/api/v1/recipients \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-

The response masks the URL — config.url never comes back in plaintext after creation:

{
"id": 51,
"name": "on-call-slack",
"type": "slack",
"config": {"url": "https://hooks.slack.com/services/T00000000/B00000000/********"},
"default": false,
"status": "active",
"events": ["down", "up", "flapping"],
"monitor_ids": [],
"created_at": "2026-05-19T12:00:00Z",
"updated_at": "2026-05-19T12:00:00Z"
}

Verify delivery before relying on the recipient:

Terminal window
curl -X POST https://api.monitive.com/api/v1/recipients/51/test \
-H "Authorization: Bearer $MONITIVE_API_KEY"
{"recipient_id": 51, "type": "slack", "status": "delivered", "response_code": 200}

Rotating the URL. There’s no separate rotate endpoint — PATCH the recipient with a new config.url. PATCH performs the cutover immediately: as soon as it succeeds, the recipient’s live webhook is the new URL, before anything has confirmed Slack will accept it. This sequence is not gap-free — between a successful PATCH and a successful POST .../test, a real alert delivers only to the unverified replacement, and if that test fails or is blocked by the 1-per-minute test rate limit (see Plan limits), GET only ever returns the masked URL, so the old webhook can’t be recovered unless you retained its plaintext value yourself.

Before rotating, save the current plaintext URL somewhere safe — it’s your only way back if the new one doesn’t work, since um-api never returns a stored webhook URL in plaintext again. Create the replacement webhook in Slack, then test it directly against Slack, bypassing um-api, to confirm Slack accepts it before the recipient’s live URL changes:

Terminal window
curl -X POST "$SLACK_WEBHOOK_URL" -H 'Content-Type: application/json' -d '{"text": "test"}'

A 200 response with body ok means Slack accepts the new URL. Only then PATCH the recipient:

Terminal window
read -rsp 'New Slack webhook URL: ' SLACK_WEBHOOK_URL; echo
printf '%s' "$SLACK_WEBHOOK_URL" | jq -Rs '{config: {url: .}}' \
| curl -X PATCH https://api.monitive.com/api/v1/recipients/51 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-

A PATCH that only sends name, events, or default leaves the stored URL untouched. A PATCH whose config omits both url and channel fails with config must set url or channel. Sending the masked value back (the ******** you’d copy from a GET or from the app’s “Current:” line) fails too — see Troubleshooting.

POST /api/v1/recipients/51/test the recipient the same way as Verify delivery above. If it fails, PATCH the retained old URL back immediately to restore delivery before troubleshooting further — only revoke the old webhook in Slack once the new URL’s test succeeds. A PATCH that succeeds only proves um-api accepted the URL’s shape, not that Slack will accept deliveries to it.

Attach the recipient to a monitor the same way as any other recipient type — through PUT /api/v1/monitors/{monitorID}/recipients, or at creation time via create_monitor’s recipient_ids/recipients arguments — see Choose who gets alerts.

Through MCP, create_monitor’s recipients argument can attach an existing Slack recipient by id at monitor-creation time; creating the Slack recipient itself has no MCP tool today — use the REST API or the dashboard for that.

  • Webhook URL length: up to 2048 characters (maxSlackURLLen in um-api’s internal/webhook/slack.go).
  • Channel override length: optional config.channel, # or @ followed by 1–80 characters with no whitespace or control characters (slackChannelShapeRe/validateSlackChannel in um-api’s internal/api/recipients.go). This is a legacy, API-only option for webhooks that still allow a channel override — most webhooks route to the channel you picked when you created them in Slack, so pick the right channel there instead of relying on config.channel.
  • Test send rate: 1 request per minute per recipient (recipientTestLimiter in um-api’s cmd/dispatcher/main.go). Going over it returns 429 with a Retry-After header; the app shows “Wait Ns before testing …”.

See Choose who gets alerts for the recipient name length limit (255 bytes) shared by every recipient type.

A real alert or test send fails with no_service. Slack returns no_service when the webhook has been removed, or the Slack app it belongs to was uninstalled or had its webhook revoked. Create a new webhook in Slack and PATCH the recipient’s config.url to the new value — there’s no way to reactivate the old URL. A no_service response is a terminal 4xx: um-api does not retry it, for a test send or a real alert.

A real alert fails with a different Slack 4xx error, like invalid_token, channel_not_found, or channel_is_archived. These are examples of the error strings Slack’s own incoming-webhooks docs describe, not an exhaustive list — um-api passes Slack’s response body through unchanged. Any non-2xx response other than a transport error, 429, or 5xx fails the delivery immediately with no retry, the same as no_service above.

Creating or updating the recipient returns 400 with config.url must be a Slack incoming webhook URL (https://hooks.slack.com/services/{team}/{bot}/{token}). The most common cause is pasting the masked value shown by GET or by the app’s “Current:” line — the ******** suffix doesn’t parse as a real webhook URL. Paste the real URL from Slack, not a masked one.

The same 400 shows up for a URL that isn’t hooks.slack.com. A Slack Workflow Builder URL, a /triggers/ webhook, or any other Slack URL that isn’t the classic https://hooks.slack.com/services/{team}/{bot}/{token} shape fails the same validation — Slack recipients only accept an incoming-webhook URL in that exact form.

Send test returns 429. You’ve hit the 1-request-per-minute test limit for that recipient (see Plan limits). Wait for the Retry-After header’s duration and try again — this limit only applies to Send test, not to real alert delivery.

Send test returns 502 with status: "failed". That’s a transport error reaching Slack — the request to hooks.slack.com itself failed, rather than Slack responding with an error. Unlike a real alert, a test is never retried: it reports this result once and stops. A real alert that hits the same kind of transport error, or a 429 or 5xx from Slack, does go through the normal retry schedule — only a Slack-side 4xx like no_service fails a real alert immediately.

Send test returns error: "invalid stored Slack URL". The URL currently stored on the recipient no longer parses as a valid Slack webhook URL. PATCH the recipient with a fresh, valid config.url from Slack.