{"canonical_url":"https://engineer.company/glossary/webhook/","content_markdown":"# webhook\n\n## What it is\n\nA webhook is an HTTP request that one service sends to another the moment\nsomething happens on its side: a payment goes through, an invoice is paid, a\nlong task finishes. The receiving side registers a URL in advance, and the\nsender posts a description of each event to it. The Standard Webhooks\nspecification calls webhooks “a common name for HTTP callbacks” and describes\nthem as a channel through which one service announces an event to another. The\nterm is sometimes written as two words, web hook, but Stripe, GitHub and the\nspecification all write it as one.\n\nThe specification also describes a webhook as part of a service's API, a kind\nof API running in reverse. Normally the client calls the service when it wants\nsomething. With a webhook, the service calls the client when it has news. In a\ntypical API integration both sides run HTTP servers, one to receive API calls\nand the other to receive webhooks. A service may also send webhooks without\noffering a request API of its own. The sender is called the producer, the\nreceiver the consumer, and the URL the receiver registers is its webhook\nendpoint.\n\nThe specification recommends an HTTP POST with a JSON body, but does not\nrequire a particular payload format or shape. Its suggested body has a `type`,\nwritten with full stops and grouped hierarchically, such as `invoice.paid`; a\n`timestamp` for when the event occurred, in ISO 8601; and the event data\neither under `data` or at the top level. Additional metadata may appear in\neither place. Delivery metadata goes in headers: `webhook-id` identifies the\nevent, `webhook-timestamp` records when this attempt was made, in Unix\nseconds, and `webhook-signature` authenticates it. Stripe and GitHub use\nheader names of their own, `Stripe-Signature` and `X-Hub-Signature-256` among\nthem, and their verification rules differ: Stripe signs an attempt timestamp\nwith the body, while GitHub's HMAC covers the body alone.\n\nA payload can be full, carrying the whole changed object, or thin, carrying\nlittle more than an identifier and leaving the receiver to fetch the rest\nthrough the API. The specification weighs the two. A full payload saves the\nreceiver extra API calls. A thin one means less data to generate and send, more\nflexibility and more room to change later, since a thin payload can always grow\ninto a full one but not the other way round. It also makes data access\nauditable, because the receiver has to ask explicitly for what it reads. Either\nway the specification advises keeping payloads small, usually under 20 kB.\nStripe offers a thin format and marks it as the recommended one.\n\n## Why it matters\n\nWithout webhooks, a system that needs to know about a change somewhere else has\nto poll: ask again and again, mostly to hear that nothing has happened, and\nstill learn about the change only at the next poll. A webhook turns that around.\nThe service that knows about the event calls once, when it happens. That is how\npayment providers, code hosting services and email providers report back to the\nsystems built on them.\n\nThe reversal has costs, and most of them land on the receiving end. Its\nendpoint is a public URL that anyone on the internet can POST to, and nothing\nabout an incoming request shows who sent it, so the specification makes\nverifying authenticity a requirement for any secure implementation. Delivery\nis retried until the receiver answers with a 2xx status or the delivery policy\ngives up, so the same event can arrive more than once; Stripe warns that\nendpoints might occasionally receive duplicates. Order is not promised either:\nStripe states plainly that it does not guarantee events arrive in the order\nthey were generated.\n\nThe producer, for its part, has to keep trying. The specification recommends a\nretry schedule spanning several days, with exponential backoff and some random\njitter. Its example makes ten attempts, the last one 75 hours, 35 minutes and 5\nseconds after the first. Stripe retries for up to three days in live mode. A\nreceiver that comes back within that window catches up on its own; after it,\nStripe lets you resend an event by hand for up to 15 days after it was created,\nor up to 30 days with its CLI. When delivery keeps failing for a long time, the\nspecification recommends that the producer tell the consumer through another\nchannel, such as email, and disable the endpoint.\n\n## What it looks like in practice\n\nThese are the headers of a delivery in the specification's format. The\nidentifier, timestamp and signature are the example values the specification\nitself uses; the `Host` value and the path are made up:\n\n```http\nPOST /webhooks/billing HTTP/1.1\nHost: example.com\nContent-Type: application/json\nwebhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W\nwebhook-timestamp: 1674087231\nwebhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=\n```\n\nAnd this is the body, a thin payload from the same specification, pretty-printed\nhere. On the wire the specification recommends sending it minified:\n\n```json\n{\n  \"type\": \"contact.created\",\n  \"timestamp\": \"2022-11-03T20:26:10.344522Z\",\n  \"data\": {\n    \"id\": \"1f81eb52-5198-4599-803e-771906343485\"\n  }\n}\n```\n\nThe `v1` prefix marks a symmetric signature: HMAC-SHA256 over the event\nidentifier, the timestamp and the body joined by full stops, keyed with a secret\nunique to the endpoint. Because the identifier and timestamp are signed along\nwith the body, neither can be altered without breaking the signature. The\nspecification also allows asymmetric ed25519 signatures, marked `v1a`, and\nrecommends them when different parties are responsible for securing the producer\nand the consumer.\n\nGitHub signs its deliveries with HMAC-SHA256 too, puts the hex digest in\n`X-Hub-Signature-256` with a `sha256=` prefix, and publishes a secret, a payload\nand a signature for testing a verifier. This is a verifier in Python, checked\nagainst that example:\n\n```python\nimport hashlib\nimport hmac\n\n\ndef verify(body: bytes, secret: str, header: str) -\u003e bool:\n    mac = hmac.new(secret.encode(\"utf-8\"), body, hashlib.sha256)\n    expected = \"sha256=\" + mac.hexdigest()\n    return hmac.compare_digest(expected, header)\n\n\nsecret = \"It's a Secret to Everybody\"\nheader = (\n    \"sha256=757107ea0eb2509fc211221cce984b8a\"\n    \"37570b6d7586c22c46f4379c8b043e17\"\n)\nprint(verify(b\"Hello, World!\", secret, header))  # True\nprint(verify(b\"Hello, World! \", secret, header))  # False\n```\n\nOne trailing space in the body is enough to fail. `hmac.compare_digest` takes\nthe same time whether the strings differ early or late; GitHub's documentation\ntells you never to compare signatures with a plain `==`. A sound handler then\nworks in a fixed order: read the raw bytes, verify the signature over exactly\nthose bytes, check that the attempt timestamp is recent if the producer signs\none, check whether this event identifier has been seen before, put the event\non a queue and answer with a 2xx. The real work happens afterwards. Stripe\ngives the example of returning a 200 before marking a customer's invoice as\npaid in the accounting system.\n\nTwo projects in this site's portfolio deal with webhooks from the receiving end.\nIn the\n[Stripe and in‑app purchase entitlements](/portfolio/built-stripe-and-in-app-purchase-entitlements/),\na subscription has to survive, among other things, a webhook that arrives twice\nand a webhook that arrives out of order. In the\n[email system with failover and delivery logging](/portfolio/built-email-with-failover-and-delivery-logging/),\ninbound webhooks report what each provider did with a message, and the project\nrecords both what was sent and what came back, in a send log and a delivery\nevent table.\n\n## Where it goes wrong\n\n**The signature never matches.** A common cause is that the receiver's framework\nparses the JSON body and the code serialises it again before computing the HMAC.\nThe specification calls this a very common failure mode: JSON serialisation\ndiffers between implementations, and a single stray space invalidates the\nsignature. Stripe needs the raw body for the same reason and warns that any\nmanipulation of it makes verification fail. GitHub adds that a proxy or load\nbalancer in front of the endpoint must not modify the payload or the headers,\nand that the payload should be handled as UTF-8. Compute the signature over the\nbytes exactly as they arrived, before anything parses them.\n\n**The same event arrives twice.** Retries and network trouble both produce\nduplicates. Under the specification, `webhook-id` stays the same across every\nretry of an event and serves as an idempotency key; its example is to keep the\nidentifiers in Redis for five minutes. Stripe tells you to log the event IDs you\nhave processed and skip ones you have seen. It also notes that one underlying\noccurrence can produce two distinct Event objects; you can recognise those by\nthe object ID in `data.object` together with the event type. GitHub's\n`X-GitHub-Delivery` header stays the same when a delivery is redelivered.\nProcessing should be idempotent, so a second delivery changes nothing.\n\n**A captured delivery is played back.** A valid signature stays valid, so an\nattacker who intercepts one delivery can send it again. That is why the\ntimestamp is signed: the specification says to reject a `webhook-timestamp`\noutside an allowed tolerance. Stripe's libraries default to five minutes,\nStripe warns that a tolerance of 0 switches the check off entirely, and it\nrecommends NTP to keep the server's clock accurate. Both Stripe and the\nspecification put a fresh timestamp on every retry, so age is measured from\nthat attempt, not from the original event; a delayed attempt can still fall\noutside the tolerance. Keep the seen identifiers for at least as long as the\ntolerance, and anything replayed inside the window is caught as a duplicate.\n\n**Events arrive out of order.** Stripe's example: creating a subscription might\nproduce `customer.subscription.created`, `invoice.created`, `invoice.paid` and,\nif there is a charge, `charge.created`, and nothing guarantees they arrive in\nthat order. The `created` field on Stripe snapshot events has one-second\nresolution, allowing several events to carry the same timestamp, and Stripe says\nnot to use it to order events or detect duplicates. The robust approach treats\nan event as a notice that something changed and fetches the object's current\nstate from the API before acting on it.\n\n**The handler is too slow.** GitHub expects a 2xx within 10 seconds; after that\nit terminates the connection and counts the delivery as failed. The\nspecification recommends a request timeout of somewhere between 15 and 30\nseconds. A handler that does its real work inline times out, the producer\nretries, and the work runs twice. Stripe and GitHub both recommend a queue.\nStripe points to the spike at the start of the month, when all subscriptions\nrenew.\n\n**Only a 2xx counts.** Anything else is a failure, a 3xx included, to the\nspecification and to Stripe alike, so an endpoint that moved behind a redirect\nfails every delivery until its registered URL is updated. The specification\ngives a few codes a meaning for the producer: a `410 Gone` means disable the\nendpoint, a 429, 502 or 504 means slow down, and a `retry-after` header should\nshape the next attempt.\n\n**For the producer, the URL is hostile input.** Customers can enter any URL they\nlike, and the producer's servers will call it. The specification calls webhook\nsystems especially vulnerable to server-side request forgery (SSRF): a URL that\npoints at an internal address makes the producer call into its own network. Its\nadvice is to send every webhook request through a proxy that filters internal IP\naddresses, such as Stripe's smokescreen, and to run the webhook workers in a\nprivate subnet that cannot reach internal services.\n\n## Further reading\n\n- [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)\n  — version 1.0.0: payload structure, the signature scheme, headers, the retry\n  schedule, status-code handling and SSRF.\n- [Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)\n  — thin and snapshot payloads, retries, duplicate and out-of-order events, and\n  replay protection.\n- [Best practices for using webhooks](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)\n  — GitHub's list: few events, a webhook secret, HTTPS, an answer within 10\n  seconds, redelivery and `X-GitHub-Delivery`.\n- [Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)\n  — `X-Hub-Signature-256`, constant-time comparison and a test example to check\n  a verifier against.\n\n\u003chttps://engineer.company/glossary/webhook/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"How a service tells your server that something happened, what a signed delivery looks like, and why the receiving end must expect duplicates and retries.","formats":{"gemtext":"https://engineer.company/glossary/webhook/index.gmi","gopher":"https://engineer.company/glossary/webhook/gophermap","html":"https://engineer.company/glossary/webhook/","json":"https://engineer.company/glossary/webhook/index.json","markdown":"https://engineer.company/glossary/webhook/index.md","pdf":"https://engineer.company/glossary/webhook/index.pdf"},"kind":"page","language":"en","title":"What is a webhook?","url":"https://engineer.company/glossary/webhook/","version":1}