---
title: "Send alerts to Slack"
description: "Create a Slack recipient from an incoming webhook URL, test it, attach it to monitors, and rotate the URL without losing the recipient."
doc_version: "1"
last_updated: "2026-11-19"
---

## What it does

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](/docs/guides/alert-recipients/) 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](/docs/guides/email-alerts/) or a webhook recipient's signing secret.

## Set it up in the app

First, get an incoming webhook URL from Slack:

1. Create a Slack app at [api.slack.com/apps](https://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](#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](/_astro/slack-alerts-1-create.CYfJ0u30.png)

4. Before attaching it anywhere, use the **Send test** row action on the Recipients page to confirm Slack actually accepts the URL — see [Troubleshooting](#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.
5. 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](/docs/guides/alert-recipients/).

**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](#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](#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.

## Do the same through the API or MCP

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:

```bash
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:

```json
{
  "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:

```bash
curl -X POST https://api.monitive.com/api/v1/recipients/51/test \
  -H "Authorization: Bearer $MONITIVE_API_KEY"
```

```json
{"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](#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:

```bash
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:

```bash
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](#troubleshooting).

`POST /api/v1/recipients/51/test` the recipient the same way as [Verify delivery](#do-the-same-through-the-api-or-mcp) 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](/docs/guides/alert-recipients/#do-the-same-through-the-api-or-mcp).

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.

## Plan limits

- **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](/docs/guides/alert-recipients/) for the recipient name length limit (255 bytes) shared by every recipient type.

## Troubleshooting

**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](#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.