How webhooks work and how to sign a payload
A webhook is an HTTP request one system sends to another when something happens. Instead of you asking “anything new?” every minute, the other side tells you the moment an event occurs.
Polling versus pushing
Without webhooks, your code has to poll: call the provider’s API on a timer and compare results. That wastes requests when nothing changed and adds delay when something did. With a webhook you register a URL once. When an event fires, such as a payment completing or a form being submitted, the provider sends a POST request with a JSON body describing it to that URL.
Anatomy of a webhook request
- Method: almost always POST.
- Body: JSON with an event type, an event ID, a timestamp and the data, for example
{"id": "evt_123", "type": "order.paid", "created": 1700000000, "data": {...}}. - Headers: a content type, and usually a signature header and a timestamp header.
Your endpoint must reply quickly with a 2xx status. Most senders treat anything else, or a timeout, as a failure and try again later.
Why signatures matter
Your webhook URL is public. Anyone who learns it can post fake events to it. To stop that, the sender and receiver share a secret. The sender computes an HMAC of the raw body with that secret and puts the result in a header. The receiver repeats the calculation and compares. If the body was changed or the secret is wrong, the values differ.
Including the timestamp in the signed text, and rejecting requests older than a few minutes, also blocks replay of an old captured request. The exact format differs between providers, so always follow the provider’s own documentation for what is signed and how it is encoded.
HMAC-SHA256 signature calculator
The calculator runs in your browser with the built-in Web Crypto API and sends nothing anywhere. Use it with test secrets to check that your own code produces the same hex string. Do not paste a production secret into any web page.
Receiver checklist
- Read the raw request body before any JSON parsing. Re-serialised JSON can differ by one space and break the signature.
- Recompute the HMAC and compare with a constant-time comparison function, not
==. - Reject the request if the timestamp is too old.
- Store the event ID and skip events you have already handled. Retries mean duplicates are normal.
- Reply 200 straight away and do slow work in a background job.
Common mistakes
- Committing the webhook secret to a repository. Keep it in an environment variable.
- Trusting the event data blindly. For money-related events, fetch the object from the provider’s API to confirm its state.
- Assuming events arrive in order. Use the timestamps, not arrival order.
Questions
Is HMAC the same as encryption?
No. HMAC proves who sent the message and that it was not changed. The body itself stays readable, so send webhooks only to HTTPS endpoints.
What if my signature never matches?
Check the secret for stray spaces, check that you sign the raw bytes, and check whether the provider expects hex or Base64 output.