Create an account-level recipient

type is webhook, email, slack, or pagerduty. For type=webhook, the response includes secret — shown exactly once, here, and never again on any subsequent read; config.url must point to a public hostname (SSRF hardening, same rule as the deprecated webhook alias). For type=email, the response carries no secret (every email recipient shares the fixed empty string internally); config.address is required instead of config.url, and the recipient starts status=pending until the mailed confirmation link is followed — see POST /email/confirm/{token} and POST /api/v1/recipients/{recipientID}/confirm/resend. For type=slack (issue #359), config.url must be a Slack incoming webhook URL in the exact shape https://hooks.slack.com/services/{team}/{bot}/{token} — no port, userinfo, query string, or fragment, and no trailing slash; config.channel is optional (e.g. "#ops" or "@alice") and overrides the incoming webhook's own default channel. The response never carries secret for a slack recipient, and config.url is always masked to https://hooks.slack.com/services/{team}/{bot}/******** (or, for a stored URL that doesn't match the expected shape, the bare https://hooks.slack.com/services/********) — the real token is never echoed back. For type=pagerduty (issue #363), config.integration_key is required instead of config.url: the PagerDuty Events API v2 routing/integration key, exactly 32 characters of [A-Za-z0-9]. The response never carries secret or config.url for a pagerduty recipient, and config.integration_key is always masked to "********" plus the last 4 characters (or the bare "********" for a stored key that doesn't match the expected shape) — the real key is never echoed back. Every trigger/resolve for one outage shares one dedup_key ("<monitor_id>-<outage_id>"), but only dedup_key and payload.custom_details.monitor_id are stable across an entire outage — payload.source, payload.custom_details.monitor_name, and the resolve's own fields do not repeat the trigger's event or reason. If config.integration_key is an Event Orchestration routing key, route its rules on custom_details.monitor_id, or enable the service's Global Dedup setting, rather than on any field that can change mid-outage. config validates only the four reserved keys — url, address, channel, integration_key — against the chosen type: in any letter case, and regardless of value (including null or ""), a reserved key the type does not allow (e.g. config.address on a webhook, slack, or pagerduty recipient, config.integration_key on any type but pagerduty) is rejected with 400, as are two keys that fold to the same reserved name (e.g. url and URL). Any other key in config is not one of the four reserved names and is silently ignored. name is required (max 255 chars); events defaults to ["down","up","flapping"] when omitted and must be a non-empty subset of that set when provided.

For type=pagerduty: deleting or detaching the recipient, changing config.integration_key, or deleting or disabling the monitor or the account does NOT resolve an incident already open in PagerDuty under the old key — only the customer, or the PagerDuty service's own auto-resolve, can close it. A delivery already queued before a monitor is disabled or an account is suspended can still send.

post/api/v1/recipients

Request

  • Base URL: https://api.uptimemonitoring.com
  • URL: https://api.uptimemonitoring.com/api/v1/recipients
  • Auth: HTTP bearer

Request body

namestring required
type'webhook' | 'email' | 'slack' | 'pagerduty' required
defaultboolean
eventsstring[]

Defaults to ["down","up","flapping"] when omitted.

Response

Created, with secret

idinteger
namestring
type'webhook' | 'email' | 'slack' | 'pagerduty'
defaultboolean

When true, this recipient is attached automatically to every new monitor created on this account, at create time, in the same transaction as the monitor row. A monitor born down does NOT notify a newly-attached default recipient at creation — the create response already shows the monitor's state directly, and the default's first notification is the monitor's next qualifying transition.

status'active' | 'pending' | 'disabled'

pending: a type=email recipient awaiting confirmation (no alerts sent yet). disabled: unsubscribed (via the mailed unsubscribe link) — alerts stopped; re-enabling requires deleting and recreating the recipient, which re-confirms from scratch. active: every type=webhook, type=slack, and type=pagerduty recipient, and a confirmed, non-disabled type=email recipient.

eventsstring[]

Non-empty subset of event types this recipient is notified for.

monitor_idsinteger[]

Monitors this recipient is currently attached to. [] for none.

secretstring

HMAC-SHA256 signing secret, prefix whs_live_. Present ONLY on the POST /api/v1/recipients response for type=webhook (and the deprecated GET /api/v1/monitors/{monitorID}/webhook alias, for compatibility) — omitted everywhere else, and always omitted for type=email, type=slack, and type=pagerduty (neither a slack nor a pagerduty recipient has a secret at all — the incoming webhook URL or the routing key itself is the credential, and both live in config, masked).

created_atstring date-time
updated_atstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.