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 creates a new chokepoint-disruption webhook subscription. Wire shape is byte-compatible with the pre-migration 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. proto3 optional so the handler can distinguish "partner explicitly sent 0 (deliver every alert)" from "partner omitted the field (apply default 50)". Without optional, both serialise to the proto3 scalar default of 0 and the handler can't tell them apart — flagged in #3242 review.

Required range: 0 <= x <= 100

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.