Skip to content

Send a test and connect a notification channel (a Slack incoming webhook or a signed webhook)

POST
/v1/projects/{id}/notification-channels
curl --request POST \
--url https://beta-api.plune.ai/v1/projects/example/notification-channels \
--header 'Content-Type: application/json' \
--cookie plune_session=<plune_session> \
--data '{ "kind": "slack", "name": "QA", "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX", "events": [ "run.finished", "run.failed" ], "language": "en" }'

The owner’s: a Slack incoming webhook or a generic signed webhook (kind: webhook, #2755), the events it takes and the language of its messages. A webhook channel (#2755) is a POST of JSON to the client’s own https address: { id, event, sentAt, project: { id, name }, link, data } - id the delivery’s (the same on a retry), event the kind (test for Send a test message), data the run’s title, environment and counts, the bug’s key, n and environment, or the mission’s name (mission.question - never the question’s words) with, for mission.done, risks, passed, failed and the open questions. Headers X-Plune-Event, X-Plune-Delivery and X-Plune-Signature: t=<unix seconds>,v1=<hex> - HMAC-SHA256, keyed with the channel’s signing secret (the whole whsec_… string, UTF-8), of <t>.<the body as sent>; refuse a t more than 300 s from your clock. The address goes through Plune’s address guard (ADR 0041) on save and before every delivery: https only, a public address only (private, loopback, link-local - the cloud metadata address too -, unique-local refused, after DNS), the connection pinned to the address judged; no redirect is followed; 10 s; the answer’s body is not read. Any 2xx is sent; 410 makes the channel rejected (gone); 429 waits Retry-After; a 5xx or the network is tried up to 4 times; anything else fails that delivery. A webhook’s answer carries its signingSecret, this once. The address (and a webhook’s signing secret) is sealed under INTEGRATIONS_ENCRYPTION_KEY with the project and the kind (ADR 0083 Ж) and is in no answer. At most 1 of a kind a project for now - a Slack channel and a webhook may stand side by side (409 channel_limit). A paid plan (ADR 0083 В): from Personal, 403 with feature: notification_channels otherwise. A Slack address takes a test message first, and the channel is saved only if Slack takes it - as Test and connect of Jira and the CI: otherwise 422 with the test’s result and nothing saved, nothing in the project’s feed. Saved, its lastSentAt, urlSavedBy and urlSavedAt are the test’s; the test counts against the ten a minute a project of Send a test message (429). A webhook’s receiver is not asked here - Send a test message is; its urlSavedAt is the add’s. In the project’s feed as the field notificationChannel:<id>. Sixty a minute.

id
required
string

An id from GET /v1/projects

Media type application/json
object
kind
required
string
Allowed values: slack webhook
name
required
string
>= 1 characters <= 80 characters
webhookUrl
required

slack: a Slack incoming webhook, https://hooks.slack.com/services/…, no other host. webhook: an https address with no user name or password in it, that the address guard takes (400 address_refused otherwise). Write-only

string
<= 512 characters
events

What the channel takes: run.finished - every finished run, failed ones too; run.failed - failed runs only; a failed run is ONE message to a channel that takes both. bug - every event of a bug (bug.can_be_closed, bug.auto_closed, bug.reopened_by_regression, bug.fails_again). A mission’s events (#2197) - mission.question (a question of the mission waits for an answer) and mission.done (the mission moved to done, with its report’s numbers) - are mission; a channel takes them only when it subscribes to mission, and a new channel does not by default. Left out: run.finished, run.failed.

Array<string>
>= 1 items unique items
Allowed values: run.finished run.failed bug mission
language

The owner’s dashboard language when left out, English without one

string
Allowed values: en uk
Example
{
"kind": "slack",
"name": "QA",
"webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"events": [
"run.finished",
"run.failed"
],
"language": "en"
}

Added

Media type application/json
object
id
required
string
kind
required
string
Allowed values: slack webhook
name
required
string
<= 80 characters
events
required

What the channel takes: run.finished - every finished run, failed ones too; run.failed - failed runs only; a failed run is ONE message to a channel that takes both. bug - every event of a bug (bug.can_be_closed, bug.auto_closed, bug.reopened_by_regression, bug.fails_again). A mission’s events (#2197) - mission.question (a question of the mission waits for an answer) and mission.done (the mission moved to done, with its report’s numbers) - are mission; a channel takes them only when it subscribes to mission, and a new channel does not by default.

Array<string>
Allowed values: run.finished run.failed bug mission
language
required

The language of its messages

string
Allowed values: en uk
state
required

rejected once the receiver said the webhook is gone (Slack: no_service, or a 404; a generic webhook: 410): nothing is sent until a new address is set; paused while the tier refuses notification_channels

string
Allowed values: working rejected paused
stateReason
required

Why it is rejected: the code Slack answered, or not_found for a 404; gone - a generic webhook answered 410

string
nullable
Allowed values: no_service no_active_hooks invalid_token channel_is_archived channel_not_found team_disabled not_found gone
lastSentAt
required

When the receiver last took a message of it - a Slack channel’s test message of the add or of a new address included

string format: date-time
nullable
signingSecret

A webhook channel’s signing secret, whsec_… - only in the answer of its add and of a change with rotateSecret; never again

string
createdBy
required
string
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
urlSavedBy
required

Who set the webhook address now saved: the add, then every new address; a change of the name, events or language leaves it

string
urlSavedAt
required

When the address now saved was set - the moment Slack took its test message

string format: date-time
Example
{
"id": "5d1f0c2a-0000-4000-8000-0000000c4a77",
"kind": "slack",
"name": "QA",
"events": [
"run.finished",
"run.failed"
],
"language": "en",
"state": "working",
"stateReason": null,
"lastSentAt": "2026-11-14T10:00:00.000Z",
"createdBy": "u-shop",
"createdAt": "2026-11-14T10:00:00.000Z",
"updatedAt": "2026-11-14T10:00:00.000Z",
"urlSavedBy": "u-shop",
"urlSavedAt": "2026-11-14T10:00:00.000Z"
}

Invalid body - a slack address that is not a Slack incoming webhook, a webhook address that is not https, an event outside the list, an event named twice; or code: address_refused with reason (internal_address, unresolvable) - the address guard refused a webhook address

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No / invalid session — a CLI token is refused here

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

Not the project’s owner; or (with TIER_LIMITS_ENFORCE=true) a tier without the notification_channels permission, with feature and tier

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

Not your project, or (code: channel_not_found) no such channel in it

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

code: channel_limit - the project has 1 channel(s) of this kind; no test message was sent

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

Slack did not take the test message: nothing was saved

Media type application/json

Slack did not take the test message of an add or a new address: nothing was saved, and a channel keeps the address it had

object
error
required
string
ok
required
boolean
result
required

rejected - Slack says the webhook is gone; busy - Slack’s 429, with retryAfterSec; failed - any other answer, the network, 10 s

string
Allowed values: rejected busy failed
retryAfterSec
integer
>= 1
testedAt
required
string format: date-time
Example
{
"error": "Slack did not take the test message — nothing was saved",
"ok": false,
"result": "rejected",
"testedAt": "2026-11-14T10:00:00.000Z"
}

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}
Retry-After
integer

Seconds until the window rolls over

The server has no INTEGRATIONS_ENCRYPTION_KEY; nothing was saved or sent

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}