A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "slack",
"destination_hint": "<string>",
"description": "<string>",
"enabled": true,
"disabled_reason": "<string>",
"last_delivered_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Register an alert channel
Requires alerts:manage. A channel belongs to the organization rather than to one environment, deliberately: somebody watching an ops channel wants both environments’ bad news in one place, and the message says which environment it came from.
Chat destinations are checked against a host allowlist — hooks.slack.com for Slack, discord.com for Discord. That is not fussiness: unlike a webhook delivery, an alert carries no signature, so an arbitrary URL here would be a POST from our network to an address of somebody’s choosing.
Storing a destination says nothing about whether it works. POST /{id}/test is what finds out.
A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "slack",
"destination_hint": "<string>",
"description": "<string>",
"enabled": true,
"disabled_reason": "<string>",
"last_delivered_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Body
slack, discord, email The Slack or Discord incoming-webhook URL, or an email address. Stored encrypted and never read back.
A label, so a list of three Slack channels says which is which — the hint is only the host.
Response
Registered.
Not editable after registration: the delivery history hangs off the channel, and a channel whose kind changed is a different destination wearing another one's record.
slack, discord, email What may be shown in place of the destination: the host for a chat hook (hooks.slack.com), the address for an email. Never a fragment of the webhook path — that is the part of the credential with the entropy in it.
Your label. What tells two channels on one workspace apart, since the hint is only the host.
Why it is off when nobody turned it off — a destination the provider answered 410 or 404 for no longer exists, and we stop rather than retry into it. Empty for a channel you paused yourself.
null means nothing has ever gone out, which is the normal state on a healthy organization. It is also why the test send exists.