Verify a webhook before letting it change customer records. A plausible payload and a secret-looking URL do not establish who sent the event or whether its account and operation references are valid.
Signature verification protects a specific boundary
Webhook signature verification checks authenticity and integrity according to the sender’s supported scheme. It should precede any business mutation. Payload validation, tenant mapping, event freshness, and duplicate handling remain separate checks.
For a proposed receiver, preserve the exact request representation required by the provider and use its documented verification library or method. Stripe’s webhook documentation specifically requires the raw request body for its signature verification. Other services may define different schemes, so do not copy that requirement blindly.
Keep signing secrets server-side and out of logs. Verify that framework middleware, proxies, and error capture do not expose headers or alter the body before the supported check.
Replay a fictional customer-update fixture
A fixture claims that a customer’s preferred callback number changed. The valid delivery updates the permitted field once under the correct account. A second fixture changes one payload byte without updating the signature. The receiver should reject it with zero customer mutations.
A third fixture has a valid signature but names a record in another tenant. Authentication of the sender does not authorise that cross-account write. The application must enforce its trusted account mapping and resource rules.
| Delivery variant | Expected result |
|---|---|
| Valid supported signature | Continue to scoped payload validation |
| Missing or invalid signature | Reject before mutation |
| Body modified in transit | Verification fails under the supported scheme |
| Genuine duplicate event | Idempotent processing |
| Valid event, wrong tenant | Deny the resource boundary |
Record a safe failure log containing receipt reference, verification category, and configuration version. Do not retain the secret or full customer payload merely to prove rejection occurred.
Test the deployed request path
A unit fixture can pass while production middleware transforms the payload. Validate the actual framework and ingress configuration with the provider’s supported test mechanism in an isolated environment. Include secret rotation according to documented provider behaviour.
Strict verification can reject legitimate events if configuration is wrong. Monitor that condition and retain a supported replay or reconciliation process. Disabling verification to make deliveries appear healthy removes the boundary instead of repairing it.
This receiver design is proposed. The voice integration case study describes related backend work. Pair it with webhook secret handling.
Webhook signature FAQ
Does HTTPS authenticate the event sender?
It protects transport but does not by itself establish that the expected provider generated the payload.
Is valid signature verification sufficient for a write?
No. Validate event type, account scope, resource permission, freshness, and operation state too.
Should rejected events be retried internally?
Do not execute unverified content. Investigate configuration and use the provider’s authorised recovery path when appropriate.