Open MCP Portaldocs
ReferenceNotifications

Add a webhook destination (platform admins, browser session only)

POST
/v1/admin/notification-destinations

A webhook destination. The URL is sealed with ENCRYPTION_KEY and never returned (a Slack incoming-webhook URL is itself a credential): urlDisplay shows scheme and host only. Format json is signed; the signing secret is shown once on creation and on rotation. Format slack is unsigned ({"text": ...}). 400 invalid_name, invalid_format. 409 name_taken (names are unique within the scope), too_many_destinations (at most 10 per team and 10 for the platform), team_archived. 422 url_not_allowed (details.reason: invalid, too_long, userinfo, fragment, scheme, private_address, blocked_address; the same address policy and internal-network allowlist as MCP servers, checked again on every delivery), invalid_events (details.events lists what this destination can't receive; at least one event is required). A platform destination receives publish.requested and key.expiring for platform tokens; with teamEvents true it also receives the other non-personal events of every team (422 invalid_events when events lists one of those and teamEvents is false).

Request Body

application/json
  1. body
name*string
Length1 <= length <= 100
format*NotificationFormat

json: a signed JSON envelope (docs/notifications.md). slack: {"text": ...}, unsigned, for Slack-compatible incoming webhooks.

Value in"json""slack"
url*string

https, or http for a host in the internal-network allowlist. No user info or fragment; a query is allowed (it is sealed and never shown).

Lengthlength <= 1000
events*array<>
Items1 <= items <= 8
teamEvents?boolean
Defaultfalse
enabled?boolean
Defaulttrue

Response Body

Created; secret is shown only now (null for slack)

application/json
  1. response
data*
curl -X POST 'https://mcp.example.com/v1/admin/notification-destinations' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "format": "json",  "url": "string",  "events": [    "server.unhealthy"  ]}'
{  "data": {    "destination": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "scope": "team",      "team": {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "slug": "string",        "name": "string"      },      "name": "string",      "format": "json",      "urlDisplay": "https://hooks.slack.com/...",      "events": [        "server.unhealthy"      ],      "teamEvents": true,      "enabled": true,      "disabledReason": "failures",      "hasSecret": true,      "secretHint": "string",      "secretRotatedAt": "2019-08-24T14:15:22Z",      "previousSecretExpiresAt": "2019-08-24T14:15:22Z",      "health": {        "state": "unknown",        "consecutiveFailures": 0,        "lastSuccessAt": "2019-08-24T14:15:22Z",        "lastFailureAt": "2019-08-24T14:15:22Z",        "lastErrorClass": "not_allowed"      },      "revision": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "createdByName": "string"    },    "secret": "string"  }}