Skip to content

Webhook Subscription

HTTP callback subscription protocol — instantiates Topic-Brokered Event Distribution

Delivers a subscriber's matching events by calling its own HTTPS endpoint — a signed, retried HTTP callback — so an external system can subscribe without ever holding a broker connection.

A Webhook Subscription is a subscription whose handler is an outbound HTTP call: instead of the subscriber connecting to the broker and pulling events, the broker POSTs each matching event to a URL the subscriber has registered. Its defining move is to invert who reaches out — the receiver exposes an endpoint and waits, and the broker calls it — which is what lets a party across an organizational or firewall boundary subscribe at all, since it needs no persistent connection and no inbound access to the broker. It is one delivery mode of a subscription, not a routing or filtering mechanism: the topic match has already happened; the webhook is how the matched event reaches a consumer that lives on the far side of an HTTP endpoint.

Example

A payments platform lets merchants react to events without polling. A merchant that cannot hold a socket open registers a webhook subscription: deliver charge.succeeded events to https://merchant.example/hooks/payments. When a charge succeeds, the broker signs the event body with an HMAC computed from a secret shared with that merchant, POSTs it to the URL, and waits for a 2xx. The merchant's endpoint verifies the signature — confirming the call genuinely came from the platform and was not forged by someone who found the URL — processes the charge, and returns 200. If the endpoint is down, the broker retries with exponential backoff and, after enough failures, parks the delivery for later. The merchant integrated by exposing one URL and verifying one signature; it never opened a connection to the platform's broker at all.

How it works

  • The endpoint is the handler — the subscription's delivery target is an HTTPS URL with a declared method, an expected success response, and a timeout; that contract is the subscriber's handler.
  • Signed payloads — each call carries a signature (an HMAC over the body) so the receiver can verify origin and integrity, because a bare URL is otherwise callable by anyone who learns it.
  • Ack by HTTP status — a 2xx is the acknowledgement; anything else (or a timeout) is a failure that triggers retry with backoff, and eventual hand-off to a dead-letter path.
  • Delivery id for dedupe — a stable id per delivery lets the idempotent receiver recognize and drop the duplicates that at-least-once retries produce.

Tuning parameters

  • Retry policy — attempt count and backoff curve before giving up; aggressive retries improve delivery odds but can hammer a recovering endpoint into staying down.
  • Payload richness — send the full event, or a thin notification the receiver uses to fetch the data itself; thin payloads leak less to the endpoint but add a round trip.
  • Signing and secret rotation — the signature scheme and how often the shared secret rotates, trading operational effort against forgery risk.
  • Timeout — how long to wait for the endpoint before counting the call failed; short timeouts free broker resources but punish slow-but-healthy receivers.
  • Per-endpoint concurrency and rate — how many simultaneous calls a single endpoint receives, so a burst of events does not overwhelm the subscriber.

When it helps, and when it misleads

Its strength is reach: a subscriber integrates with nothing but an HTTP endpoint, works across company and network boundaries, and needs no standing connection or broker client. Its failure modes come from delivering to an endpoint you do not control — it can be down, slow, or return 200 while silently discarding the event; at-least-once delivery produces duplicates; and a wave of retries against a just-recovering endpoint is a thundering herd that re-breaks it. The security traps are sharp: an unsigned webhook is forgeable, and a fat payload over-shares data with an endpoint that only needed to be notified. The classic misuse is shipping full sensitive payloads to external endpoints for convenience, or omitting signatures entirely. The discipline is to sign every call and verify on receipt[1], minimize the payload (notify-then-fetch for anything sensitive), make receivers idempotent with the delivery id, and cap retries into a dead-letter rather than retrying forever.

How it implements the components

  • subscriber_handler_contract — the registered URL, method, expected 2xx, timeout, and retry expectation constitute the handler contract for a subscriber reached over HTTP.
  • authorization_and_visibility_policy — payload signing authenticates the broker to the receiver, and payload minimization governs how much a given external endpoint is allowed to see, securing the outbound delivery itself.

It defines and secures the external delivery endpoint but does not register or manage the subscription (that's Subscription API), decide who is permitted to subscribe to the topic in the first place (that's Access-Controlled Topic), route the event to it (broker_routing_boundary — Topic Exchange or Event Bus), or park a callback that keeps failing (that's Dead-Letter Queue).

Notes

A webhook shifts the operational burden onto the receiver: because the broker calls out, the subscriber must expose and defend a public endpoint, verify signatures, and be idempotent, whereas a pull-based consumer keeps all of that on its own side of a connection it initiates. Webhooks are the right delivery mode when the subscriber cannot or will not hold a connection — typically across an organizational boundary — and the wrong one for a high-throughput internal consumer, which a durable pull subscription serves far better.

References

[1] An HMAC (hash-based message authentication code) is a signature computed from the message body and a shared secret; a receiver recomputes it to confirm both that the sender knew the secret and that the body was not altered in transit. It is the standard way to make a webhook call verifiable, turning a publicly-reachable URL into one that only the legitimate broker can meaningfully call. ↩