RegisterWebhook
RegisterWebhook subscribes a callback URL to chokepoint disruption alerts. Returns the subscriberId and the raw HMAC secret — the secret is never returned again except via rotate-secret. PRO-gated. Requires an active Pro subscription.
Authorizations
User-issued WorldMonitor API key.
Headers
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.
1 - 255^[\x21-\x7E]{1,255}$Body
RegisterWebhookRequest creates a new chokepoint-disruption webhook subscription. Wire shape is byte-compatible with the pre-migration legacy POST body.
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.
8 - 2048Zero or more chokepoint IDs to subscribe to. Empty list subscribes to the entire CHOKEPOINT_REGISTRY. Unknown IDs fail with 400.
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.
0 <= x <= 100Response
Successful response
RegisterWebhookResponse wire shape preserved exactly — partners persist the
secret because the server never returns it again except via rotate-secret.
