Subscribe to events
Before you start
- A reachable HTTPS endpoint that responds quickly.
- The
webhook.createpermission.
1. Discover the event types
Query the platform for the available event types rather than working from a list written down somewhere. A transcribed list drifts from what the platform actually emits.
2. Register the webhook
Supply the destination and the event types to subscribe to.
The destination is validated before any request is made — at registration, at update, at test, and again at delivery. The resolved address is pinned, so a destination cannot pass validation and then resolve somewhere else when a real event fires.
3. Test it
Test-fire without waiting for a real event. This confirms the destination is reachable and that your consumer parses what it receives.
The result comes back to you directly. It is not written to delivery history, so do not go looking for the test there afterwards.
4. Build the consumer correctly
The delivery guarantees shape what a correct consumer looks like:
| Guarantee | Consequence for your consumer |
|---|---|
| At-most-once | Nothing is retried automatically. A failed delivery can be re-sent by hand, but nothing does it for you — reconcile periodically. |
| Short timeout | Acknowledge fast; do the work asynchronously |
| No ordering guarantee | Do not assume events arrive in sequence |
With at-most-once delivery, a consumer that assumes it sees every event will eventually be wrong — and will not know it. Treat webhooks as a low-latency notification that something changed, and reconcile against the API for correctness.
This is the single most consequential thing to get right here.
5. Verify the sender
Each delivery carries a shared secret so the receiver can confirm the caller. Note that the secret is delivered in the body for comparison, rather than used to compute a signature header. If your security review requires signature-based verification, raise it as a gap rather than assuming it exists.
6. Monitor deliveries
Delivery history for one webhook. A failed delivery can be retried from here.
Each delivery is recorded with its outcome. A pattern of failures usually means the consumer is too slow rather than unreachable — the timeout is short.
Next
Last verified against commit 74cecd91 (2026-08-03)