Skip to main content
POST
RegisterWebhook

Authorizations

X-WorldMonitor-Key
string
header
required

User-issued WorldMonitor API key.

Headers

Idempotency-Key
string

Optional client-generated idempotency key. Retrying a POST with the same key and an identical request body replays the original response (only the status, body, and Content-Type are reproduced) instead of re-executing; reusing the key with a different body is rejected with 422. For mutations this avoids duplicating the side effect, while for batch-read POSTs it replays a cached snapshot that can be up to 24 hours stale. Keys are scoped per authenticated caller (falling back to the source IP for unauthenticated endpoints) and retained for 24 hours.

Required string length: 1 - 255
Pattern: ^[\x21-\x7E]{1,255}$

Body

application/json

RegisterWebhookRequest subscribes to one eventType (default chokepoint.disruption). Wire shape is byte-compatible with the legacy POST body.

callbackUrl
string
required

HTTPS callback URL. Must not resolve to a private/loopback address at registration time (SSRF guard). The delivery worker re-validates the resolved IP before each send to mitigate DNS rebinding.

Required string length: 8 - 2048
chokepointIds
string[]

Zero or more chokepoint IDs to subscribe to. Empty list subscribes to the entire CHOKEPOINT_REGISTRY. Unknown IDs fail with 400.

alertThreshold
integer<int32>

Disruption-score threshold for delivery, 0-100. Default 50; an explicit 0 delivers every alert.

Required range: 0 <= x <= 100
eventType
string

A shared/event-triggers.json key; chokepoint.disruption when omitted.

Maximum string length: 64
countries
string[]

country.risk_surge scope: monitored ISO2 codes; empty = all.

minLiveSignal
integer<int32>

chokepoint.disruption live-signal floor; 0 = score only.

Required range: 0 <= x <= 40
scope
object

Per-event filters for occurrence events. Each key applies to the events named in its comment; the handler validates against shared/event-triggers.json and stores the defaults.

Response

Successful response

RegisterWebhookResponse wire shape preserved exactly — partners persist the secret because the server never returns it again except via rotate-secret.

subscriberId
string

wh_ prefix + 24 lowercase hex chars (12 random bytes).

secret
string

Raw 64-char lowercase hex secret (32 random bytes). No whsec_ prefix.