Update Notification Channel

PATCH /api/notification-channels/:id

Config is merged with existing secrets, preserving encrypted fields that are not provided, as long as the channel keeps its type.

Changing type is different: the stored config belongs to the old channel type, so it is discarded entirely and the config is rebuilt from the config in this request. A type change therefore requires config (otherwise 400), and secrets of the old type do not carry over.

Request Body (all optional)Copy Anchor Link

delaySeconds runs on its own timer for this channel, starting from the moment this channel would notify, independent of any other channel on the same alert. If a maintenance window starts before that time elapses, or the incident is already resolved by then, nothing is delivered on this channel.

priority has been removed from channel configuration. A request that still sends it is accepted and the field is simply ignored, so existing integrations keep working unchanged.

Example (cURL)Copy Anchor Link

curl -X PATCH "$BASE_URL/api/notification-channels/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Email Channel",
    "isActive": true
  }'

Common errorsCopy Anchor Link

• 400 Bad Request with data.code invalidRequestBody when an email or sms channel carries a recipient the delivery path could never accept. Checked for type: email in config.to and config.email, and for type: sms in config.to, config.phoneNumbers and config.phoneNumber; a comma-separated string and an array are both read as a list and every entry is checked, and the message names the first offending value. An email recipient needs exactly one @ with something on both sides and no spaces, the form Name <address> is allowed; an SMS recipient must be E.164, a +, a digit 1-9, then 7 to 14 more digits, with no spaces, dashes or brackets. These are the delivery path's own rules, so a value refused here could never have received an alert. A channel with NO recipient of its own stays valid: delivery then falls back to the customer's or the organization's stored address. Only email and sms are checked; on every other type these keys mean something else.
• 400 Bad Request with data.code invalidRequestBody when a target URL in config is not a parseable http/https URL, or points at a private, loopback or link-local address, at localhost, at a reserved private-use name (.local, .internal, .home.arpa) or at a single-label host. Every top-level config string starting with http:// or https:// counts as a target URL; fields carrying message content (bodyTemplate, webhookBodyTemplate, headers) are exempt, a link into your own network is legitimate there. The check does not resolve DNS, so a public name that only later resolves privately is stopped at delivery time instead.
• 400 Bad Request when the body fails validation (unknown type, name over 100 characters, config that is not a JSON object, allowedPackageTypes that is not an array)
• 400 Bad Request with data.code: "configRequiredForTypeChange" when type changes and no config is sent
• 401 Unauthorized when not authenticated
• 403 Forbidden when accessing channels outside your scope
• 404 Not found when the channel does not exist

ResponseCopy Anchor Link

Returns the updated notification channel object. See Error Codes for error responses.

PermissionsCopy Anchor Link

Organization admins may write channels at any level. A customer-scoped login (role readonly) may create, update and delete channels bound to one of ITS OWN customers: that is what the integrations page in the dashboard offers the role, and until 04.09.2026 the API refused it with a bare 403.

Two limits remain. An ORGANIZATION-level channel, one carrying no customerId, stays admin-only. And a channel of a customer outside the caller's scope is refused, as before. The roles editor and responder are not writers here.