Webhook signature verification sequence
Validate webhook authenticity before processing events.
Webhooks let external services notify you of events — a payment completed, a user was created, a file finished uploading. But a webhook is just an HTTP request, and an attacker can send fake requests that look identical. Webhook signature verification proves the request came from the provider you trust. The provider signs the webhook body with a secret only you and they know, and you re-compute that signature to verify authenticity before processing the event.
This diagram shows the flow: the provider signs the payload with the shared secret, sends it over the network with the signature in a header, your server extracts both the signature and the payload, re-computes the signature, and compares. If they match, the webhook is authentic and safe to process. If not, you reject it.
When to use this template
- Payment webhooks — Stripe, PayPal, Square all send signature headers. Never process a payment webhook without verifying the signature.
- Third-party integrations — GitHub, Slack, and most SaaS platforms that push data to you will include a signature. Document which header and algorithm they use.
- Security reviews and compliance — auditors ask for exactly this diagram. Showing signature verification gives confidence that your webhook handler is hardened against forgery.
How to adapt it
Customize the diagram for the specific provider:
- Change the signature header name — Stripe uses X-Stripe-Signature, GitHub uses X-Hub-Signature-256, Twilio uses X-Twilio-Signature. Update the header name to match your provider.
- Document the signing algorithm — HMAC-SHA256 is standard, but some use RSA signatures. Note which one your provider uses.
- Add queuing step — after signature verification succeeds, add a participant for a message queue (SQS, Kafka, RabbitMQ) and show the event being enqueued before returning 200 OK.
Visual edits regenerate clean Mermaid code, so you can expand this sequence with extra steps (rate limiting, deduplication) without retyping the syntax.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
sequenceDiagram
participant Provider
participant Network
participant Server as Your Server
participant Handler
Provider->>Provider: Sign payload with secret
Provider->>Network: POST /webhooks with signature header
Network->>Server: Receive webhook request
Server->>Server: Extract signature from header
Server->>Server: Recompute signature with local secret
Server->>Server: Compare signatures
alt Signatures match
Server->>Handler: Event is authentic
Handler->>Handler: Process webhook
Server-->>Network: 200 OK
else Signatures don't match
Server-->>Network: 403 Forbidden
end
Frequently asked questions
- Why do I need to verify webhook signatures?
- Without verification, an attacker can forge webhook events — fake a payment completion, a user signup, a data deletion. Signature verification proves the webhook actually came from the provider you trust. The provider signs with a secret only they and you know, and you re-compute the signature locally using your copy of the secret. If the signatures match, the webhook is genuine.
- How does the signature work technically?
- The provider computes an HMAC (or similar MAC) of the webhook body using a shared secret, then includes that HMAC in a header (e.g., Stripe sends X-Stripe-Signature). Your server extracts the body, computes the same HMAC using your copy of the secret, and compares them. If they match, the body hasn't been tampered with. Never trust the signature header alone — always re-compute it.
- What if the signature doesn't match on a legitimate webhook?
- Three possibilities: (1) you're using the wrong secret (grab the test secret from the test environment, the live secret from live), (2) the body was modified in transit or by a middleware (rare), (3) the provider changed the signing algorithm and you're using an outdated version. Return 403, log the mismatch with the webhook ID, and contact the provider's support.
- Should I process the webhook immediately or queue it for later?
- Queue it. Verify the signature and return 200 OK immediately — the provider usually gives you 2–5 seconds. Then process the event asynchronously. If processing fails, you can retry without asking the provider to re-send. This decouples verification (fast, synchronous) from processing (potentially slow, asynchronous).
Related templates
API rate limiting sequence
Client, gateway, and limiter handling a 429 with Retry-After.
API token authentication sequence
Client obtaining and using bearer tokens for API requests.
JWT token validation sequence
Client requests protected resource using access token, server validates signature.