How to verify webhook signatures with HMAC — a developer’s guide
Verify webhook signatures the right way: HMAC-SHA256, timing-safe compare, replay protection. Code examples in Node, Python and Go for production endpoints.
A webhook without verification is just an open endpoint
Webhook delivery is convenient because the sender pushes data to your system as soon as an event happens. But that same convenience becomes a security problem if your endpoint accepts any request that looks roughly correct. Without signature verification, anyone who can reach the endpoint can attempt to send spoofed payloads.
The point of webhook verification is to prove that the request body was generated by the expected sender and was not modified in transit. That should happen before the payload reaches business logic, database writes, or downstream integrations.
HMAC signatures are computed from the raw request body
Most webhook providers use an HMAC signature, usually SHA-256, computed from the exact raw request body and a shared secret. Your server recomputes the signature using the same secret and compares it to the signature header sent with the request.
The important implementation detail is that verification must use the raw body exactly as received. If your framework parses and re-serializes JSON first, the byte sequence can change and the signature check will fail even for legitimate payloads.
Verification should include timing-safe comparison and replay protection
A proper implementation does not stop at hashing the body. It should use a timing-safe equality check to avoid leaking comparison details, and it should consider replay protection if the provider includes timestamps or event identifiers. Otherwise an attacker could reuse a previously valid request.
Operationally, teams should also rotate webhook secrets, store them securely, and make failed verification visible in logs so abnormal traffic does not disappear into the background.
Verification is part of reliability, not just security
When a webhook handler verifies signatures consistently, the downstream system can trust the event stream much more confidently. That reduces false positives in automation and makes debugging easier when something goes wrong.
In document extraction workflows, that matters because webhook payloads often trigger database writes, spreadsheet inserts, accounting updates, or customer-facing actions. A bad event should fail at the gate, not halfway through the workflow.
Need this workflow in production?
DocPeel turns PDFs, images, and emails into structured JSON with integrations for webhooks, spreadsheets, and downstream tools.