Skip to content

Change a notification channel

PATCH
/v1/projects/{id}/notification-channels/{channelId}
curl --request PATCH \
--url https://beta-api.plune.ai/v1/projects/example/notification-channels/example \
--header 'Content-Type: application/json' \
--cookie plune_session=<plune_session> \
--data '{ "events": [ "run.failed" ] }'

The owner’s: its name, events, language, or a new webhook address - which makes a rejected channel working again (a webhook address through the address guard, 400 address_refused otherwise). A new Slack address takes a test message first, as the add: Slack takes it, and the whole change is saved - urlSavedBy, urlSavedAt and lastSentAt are the test’s; Slack does not, and 422 with the test’s result and nothing is saved - the channel keeps its old address and state. A change without webhookUrl sends no message and leaves urlSavedBy and urlSavedAt as they were. A webhook channel’s rotateSecret: true gives a new signing secret, in this answer only (signingSecret). Refused by the tier as the add. In the project’s feed. Sixty a minute.

id
required
string

An id from GET /v1/projects

channelId
required
string

A channel’s id from GET …/notification-channels

Media type application/json
object
>= 1 properties
name
string
>= 1 characters <= 80 characters
webhookUrl

A new address, by the rules of the channel’s kind: the channel is working again; a webhook keeps its signing secret. Write-only

string
<= 512 characters
rotateSecret

A webhook channel only: a new signing secret, in this answer’s signingSecret; the old one signs nothing more

boolean
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.

Array<string>
>= 1 items unique items
Allowed values: run.finished run.failed bug mission
language
string
Allowed values: en uk
Example
{
"events": [
"run.failed"
]
}

Changed

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.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, or nothing to change; an address the channel’s kind does not take; rotateSecret on a Slack channel; code: address_refused - 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_unreadable - rotateSecret on a webhook whose saved address cannot be opened on this server; set the address again

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

A new webhookUrl that Slack did not take a test message on: nothing was saved, the old address stays

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"
}