A webhook endpoint is a public HTTP entry point that receives events from another system. Its URL being difficult to guess is not authentication. Without signature verification, an attacker may forge events such as payment updates, account changes or subscription cancellations.
Verify the exact bytes
Most providers calculate a signature over the raw request body, sometimes combined with a timestamp or delivery identifier. Read the raw body before decoding JSON and calculate the expected signature using the exact documented algorithm. For HMAC-SHA-256, use the provider's secret and a timing-safe comparison such as hash_equals(). Do not decode and re-encode JSON before verification: whitespace and key order can change the signed bytes.
Enforce freshness
When the signature includes a timestamp, parse it strictly and reject requests outside a small, documented tolerance. This reduces replay opportunities but does not replace duplicate-delivery handling. Keep clocks synchronized on the receiving server. Rotate webhook secrets using the provider's supported overlap procedure.
Validate after authentication
A valid signature proves that the sender knows the secret; it does not prove that every field is valid for your application. Validate event type, required fields, identifier format and expected state transitions. Do not trust a client-supplied amount or account ID without checking the corresponding server-side record.
A safe processing sequence
- Enforce request size and content-type limits.
- Read the raw body and verify signature and timestamp.
- Parse JSON and validate the event envelope.
- Persist the delivery ID and event for controlled processing.
- Return the provider's expected acknowledgement promptly.
Further reading
- GitHub: Validating webhook deliveries — https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
- Stripe: Webhook signatures — https://docs.stripe.com/webhooks/signature