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
2xxis 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[n1], 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, expected2xx, 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).
Related¶
- Instantiates: Topic-Brokered Event Distribution — it is the delivery mode that lets connection-less, external subscribers receive their topic's events.
- Consumes: Subscription API — a webhook subscription is created and managed as a subscription through it.
- Sibling mechanisms: Subscription API · Access-Controlled Topic · Dead-Letter Queue · Delivery Acknowledgement · Topic Exchange or Event Bus
Editorial Notes¶
Form Classification¶
Form family: Control, Automation & Runtime
Rationale: Webhook Subscription operates as a live operational control that automatically routes, enforces, adapts, or responds during execution because it 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.
Independent corroboration: The frozen evidence defines Webhook Subscription as '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', so its operative form is Control, Automation & Runtime.
Nearest alternative: Protocol, Workflow & Routine — Webhook Subscription includes features of a repeatable ordered procedure or handoff sequence that coordinates action, but its defining operation is a live operational control that automatically routes, enforces, adapts, or responds during execution.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Specialized
Rationale: Both independent reviews identify computer science as the historical home of the operation—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.. The retained alternates document formative adjacent traditions; the reach field, not the origin field, carries later applicability.
Related originating lineages:
- Data Science & Analytics — Data science's modeling, validation, and monitoring tradition contributes a separate formative lineage to the mechanism's webhook subscription logic.
- Engineering & Design — Engineering design, reliability, and systems-safety practice supplies a parallel or contributing lineage for the mechanism's defining operation: 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….
- Security Studies & Intelligence Analysis — Security engineering, threat analysis, and intelligence practice supplies a parallel or contributing lineage for the mechanism's defining operation: 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….
Review resolution: Both blind reviewers independently place the defining operation—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.—in computer science. Their queued differences are secondary: alternate_origin_disagreement, origin_mode_disagreement, domain_reach_disagreement, encyclopedia_synthesis_disagreement. Reviewer A uniquely contributes ['data_science']; reviewer B uniquely contributes ['engineering_design', 'security_intelligence']. I preserve the full evidence-supported union of 3 alternate domain(s), without a numeric cap. origin_mode=single_lineage reflects the more specific lineage judgment in reviewer B's evidence, while domain_reach=specialized separately records present-day portability. The affirmative encyclopedia-synthesis finding is preserved, and confidence=high uses the more conservative reviewer level.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; high confidence.
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.
[n1] 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. ↩