Declare a platform alert destination

post

https://staging.ankatech.co/api/v3/admin/platform/alerts/destinations

Creates a destination. The endpoint is validated BEFORE anything is persisted: a
rejected URL leaves no row and opens no socket.

A webhook's signing secret is supplied here as the MATERIAL, and is MANDATORY on
create: a webhook declared without one is rejected with 400 rather than persisted. The
platform never sends an unsigned webhook, so an unsigned destination is one no alert
could ever be delivered to — a saved row and a green form that go quiet forever. (On
replace the secret is optional, where omitting it means "leave the sealed value
alone".) Its custody reference is derived server-side from the created row's immutable
id and is never accepted from the caller — the custody registry is shared with the IdP,
event-forwarding and observability subsystems, so a caller-supplied reference would let
this destination bind to a credential it has no claim to.

A webhook URL is validated STRICTLY regardless of deployment type, as is any
destination whose purpose is HEARTBEAT.

Authorization: admin.platform.alerts.write.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Declares or replaces a platform alert destination.

channel

string

enum

required

Delivery channel.

Allowed:

purpose

string

enum

required

ALERT receives the fired catalogue; HEARTBEAT is the outbound dead man's switch, whose ABSENCE is the signal. HEARTBEAT is validated strictly for SSRF regardless of deployment type: a receiver on the internal network dies with the thing it exists to report on.

Allowed:

config

required

Per-channel configuration. Its channel field must equal the channel above; a mismatch is rejected rather than silently resolved, because either value could be the intended one and guessing produces a destination the operator did not ask for.

acceptedSeverities

array of strings, unique

required

length ≥ 1

Severities this destination accepts.

enabled

boolean

Defaults to true

Whether this destination is delivered to. Defaults to true.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

JWT

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

201The created destination.

400Invalid request: a malformed field, a config whose channel does not match the declared channel, or a WEBHOOK config carrying no signing secret — the secret is mandatory on create, because the platform never sends an unsigned webhook and would never be able to deliver to such a destination.

401Unauthorized: missing or invalid JWT.

403Forbidden: missing scope, or not the platform tenant.

409A destination with this channel, purpose and endpoint already exists. Also returned when another ENABLED HEARTBEAT destination already exists: the heartbeat rides exactly one LIVE receiver, because with two one can go silent while the other keeps arriving. A DISABLED standby is admitted.

422The endpoint is well-formed but not a permitted target (SSRF guard). Oracle-safe: the body never echoes the host, the resolved address, or which rule refused it.