Webhook Signature Verifier

Why Webhook Signature Verification Is Non-Negotiable

Webhooks are a fundamental part of modern web architecture, allowing services like Stripe, GitHub, and Shopify to notify your application when events occur in real-time. Because these requests are sent over the public internet to a publicly accessible endpoint on your server, there is inherently a risk of spoofing. If an attacker discovers your webhook URL, they could simulate a "payment successful" event, potentially tricking your system into providing services or fulfilling orders for free.

To mitigate this, providers implement webhook signatures using HMAC (Hash-based Message Authentication Code). When the provider sends a webhook, it uses a shared secret (known only to you and the provider) to generate a cryptographic hash of the payload. Your server receives the payload and the signature, uses the same shared secret to generate its own hash, and compares the two. If they match, you know the request is genuine. If you are exploring how HMAC generation works in detail, you can check out our HMAC Generator. Additionally, managing these secrets securely is critical; consider using a Secret Scanner to ensure webhook secrets aren't accidentally committed to your codebase.

How Stripe Webhook Signatures Work

Stripe has one of the most robust webhook signature implementations, designed specifically to prevent replay attacks. A replay attack occurs when an attacker intercepts a valid webhook request (including its valid signature) and resends it later to trigger the same action multiple times.

Stripe prevents this by including a timestamp in the signature calculation. The Stripe-Signature header typically looks like this: t=1492774577,v1=5257a869.... Here, t is the Unix timestamp of when the event was sent, and v1 is the HMAC-SHA256 signature.

To verify a Stripe webhook, you must:

• Extract the timestamp and the signature from the header.
• Concatenate the timestamp and the raw request body, separated by a period (e.g., timestamp.payload).
• Compute the HMAC-SHA256 hash of this concatenated string using your endpoint secret (which usually starts with whsec_).
• Compare the computed hash to the provided v1 signature.
• Check that the difference between the current time and the timestamp is within your allowed tolerance (usually 300 seconds).

GitHub Webhook Signatures: SHA-256 vs SHA-1

GitHub allows you to configure a secret for your organization or repository webhooks. When an event triggers, GitHub computes an HMAC signature of the raw payload using this secret.

Historically, GitHub provided this signature in the X-Hub-Signature header using the SHA-1 algorithm. However, due to the vulnerabilities associated with SHA-1, modern implementations use SHA-256. The secure signature is provided in the X-Hub-Signature-256 header, prefixed with sha256= (for example, sha256=7d38cdea...).

Unlike Stripe, GitHub does not embed a timestamp directly into the signature header to prevent replay attacks. Therefore, it is up to your application to implement idempotency (ensuring that processing the same event ID multiple times does not result in duplicate actions). When developing custom API integrations, you might also want to generate test keys using our API Key Generator.

Shopify Webhook HMAC Verification

Shopify secures its webhooks by computing an HMAC-SHA256 hash of the raw request body using your app's client secret. They encode this hash in Base64 rather than hexadecimal, which is a common stumbling block for developers used to Stripe or GitHub.

The signature is sent in the X-Shopify-Hmac-Sha256 HTTP header. To verify it, you simply compute the HMAC-SHA256 of the raw body using your app secret, encode the result in Base64, and ensure it matches the header. Because it is sensitive to the exact byte structure, parsing the payload as JSON and then stringifying it before verification will almost always result in an invalid signature. If you ever need to inspect what headers are being sent in your environment, our HTTP Header Analyzer can be a helpful debugging tool.

Common Reasons Webhook Signatures Fail

Debugging failed webhook signatures can be frustrating. Here are the most common pitfalls:

• Modifying the Raw Body: Frameworks like Express (Node.js) or Django (Python) often automatically parse incoming requests into JSON objects. If you then stringify that object to verify the signature, the spacing, formatting, or key ordering might differ from the original raw payload, causing the hash to change. You must verify the signature against the raw, unparsed byte stream.
• Wrong Secret Key: Ensure you are using the correct webhook secret. For Stripe, the webhook endpoint secret (whsec_...) is different from your API keys. Additionally, test environments and live environments have different secrets.
• Timestamp Skew: For Stripe, if your server's clock is out of sync or if the webhook was delayed in transit, the timestamp might fall outside your tolerance window.
• Encoding Mismatches: Ensure you are comparing apples to apples. GitHub uses hexadecimal strings, while Shopify uses Base64.

Building Your Own HMAC Webhook Receiver

If you are building an API that sends webhooks to your customers, implementing a robust signature system is highly recommended. Using HMAC-SHA256 is the industry standard. For added security, incorporating a timestamp like Stripe does will protect your users from replay attacks. Similar cryptographic patterns are used in JSON Web Tokens; you can explore this by using our JWT Signature Verifier.

This Webhook Signature Verifier provides a "Custom HMAC" option specifically for developers building their own integrations. You can test payloads against various algorithms (SHA-1, SHA-256, SHA-512) and encodings (Hex, Base64) to ensure your implementation generates exactly the expected output before shipping to production.