What Is a Webhook?

What It Is

A webhook is an event-driven callback: one system pushes real-time data to a consumer the instant an event occurs. The consumer provides a URL. The producer sends an HTTP POST to that URL when something happens. No polling. No waiting. The event drives the transmission.

Why It Matters

Polling is waste. You ask, ask, ask, and 999 times out of a thousand the answer is "no change." A webhook inverts the control: the producer speaks when it has something to say. This is not merely an optimization — it is a philosophical shift from imperative to reactive. In open, deterministic systems, every unnecessary call is an attack surface and a cost sink. Webhooks eliminate both.

They also make systems auditable. Every event leaves a trace: a POST, a timestamp, a signature. You can replay the chain. You can verify the origin. In a world where "trust but verify" is table stakes, webhooks turn that into an interface, not a checkbox.

How It Works

1. The consumer registers an endpoint. It tells the producer: "When X happens, POST to this URL." This is the subscription. The URL is a contract. It must be stable, reachable, and idempotent-ready.
2. The event fires. A payment succeeds. A build completes. A file lands. The producer detects the state change.
3. The producer builds the payload. It serializes the event into a structured body — usually JSON — with enough context to act on. Timestamps, IDs, nested state. The payload should be self-describing. A bare ID is not enough.
4. The producer sends the POST. The HTTP request includes a signature header so the consumer can verify origin. No signature, no trust. The producer retries on transient failures, with exponential backoff, but not forever. It does not block its own state on a consumer's timeout.
5. The consumer responds. HTTP 200 means "got it." 2xx is the only success band. Everything else is failure or retry. The consumer must respond fast. It should ACK the webhook, queue the work, and return. Heavy processing inside the HTTP handler is a trap.
6. The consumer acts. The queued work runs: update a database, trigger a notification, start a downstream job. The webhook is the spark, not the engine.

The Contract

• Method: POST
• Content-Type: application/json
• Body: A single JSON object. No arrays at the root. No null keys where meaning is required.
• Headers: At minimum, a signature header (X-Webhook-Signature, Stripe-Signature, etc.) containing a timestamped HMAC of the payload. The consumer verifies the HMAC with a shared secret.
• Idempotency: The producer should include an event ID. The consumer must reject duplicates. Idempotency-Key is not optional at scale.
• Retry policy: Exponential backoff with jitter, capped at a max age (e.g., 24 hours). After that, dead-letter the event. Do not retry 4xx errors.
• Timeout: The producer should not wait more than a few seconds. If the consumer does not respond in time, the producer retries.
• Ordering: Webhooks do not guarantee ordering. If order matters, the payload must include a sequence or the consumer must reassemble from state.
• Resilience: The consumer must tolerate out-of-order, duplicate, and late deliveries. The webhook contract is at-least-once, not exactly-once.

Real Examples

Stripe. When a payment succeeds, Stripe POSTs to your configured URL. The payload includes payment_intent, amount, currency, and a livemode flag. You verify the Stripe-Signature header, parse the event, and fulfill the order. No cron job asking Stripe "anything new?" every 30 seconds.

GitHub. A push to main fires a webhook to your CI runner. The payload has the commit SHA, the branch ref, the author, and the full diff URL. Your CI triggers the build pipeline. The same mechanism powers PR reviews, issue labels, and release events. GitHub has no idea what your CI does. It just delivers the event.

Cloudflare Workers. A D1 database change triggers a webhook to an analytics worker. The worker aggregates, writes to R2, and returns 200. The database stays fast. The analytics stays real-time. No ETL pipeline, no batch job, no 15-minute lag.

Twilio. An incoming SMS hits Twilio. Twilio POSTs to your webhook URL with the body, the sender number, and the message SID. Your app parses the body, routes it to the right handler, and replies. The webhook is the entire input surface for the interaction.

Sentry. When an error threshold is breached, Sentry POSTs to PagerDuty or Slack. The payload includes the error fingerprint, the release version, the environment, and the stack trace. The on-call engineer is paged in seconds, not after the next polling cycle.

Common Mistakes

Treating the POST as a command. A webhook is a notification, not a command. The consumer decides what to do. The producer does not wait for a result.

Doing heavy work inside the HTTP handler. The producer's timeout is a guillotine. Respond fast. ACK the webhook. Process asynchronously. Slow handlers cause retries, which cause double-work, which causes data corruption.

Ignoring signature verification. If you accept any POST to your webhook URL, you are building a backdoor. Verify the HMAC. Verify the timestamp is not stale. Reject everything else.

Relying on ordering. Webhooks arrive out of order. If you process a "subscription canceled" before a "subscription created," you must tolerate it gracefully. State machines, not event chains.

No idempotency. A webhook can fire twice. If your handler increments a balance without checking the event ID, you are leaking money. Every event is a potential duplicate until proven otherwise.

Hard-coding URLs in the producer. The consumer must be able to rotate endpoints. Webhook URLs are not config constants. They are runtime subscriptions.

Connection to OIP

The Open Information Protocol (OIP) is built on three principles: open (anyone can inspect the interface), deterministic (the same input always produces the same output), and auditable (every action is traceable and verifiable). Webhooks embody all three.

They are open because the contract is a URL and a JSON schema. No proprietary SDK required. Any consumer that speaks HTTP can participate. The interface is the documentation.

They are deterministic because the event is the fact. The payload is the canonical record of the state change. There is no hidden query, no opaque mutation, no side effect the consumer cannot see. What you POST is what happened.

They are auditable because every webhook is a signed, timestamped HTTP request. You can log it, replay it, hash it, and verify it. The chain of custody is in the headers. The producer's signature proves origin. The consumer's 200 proves receipt. The event ID proves uniqueness. This is not a feature — it is the architecture.

In the OIP philosophy, a webhook is not a convenience. It is a binding notification of state change, pushed over an open wire, signed by its origin, and consumed by any system that can speak the protocol. It is the simplest possible way to keep distributed systems honest.

Connection to the Grain Philosophy

This protocol is part of the Open Inventory Protocol — a living system of self-describing voxels that serves the Grain philosophy. The OIP is the interface. The philosophy is the core.