Webhook Signature Verification
Webhook signature verification is validating that an incoming webhook was sent by the expected provider and was not altered. Providers sign each payload with a shared secret, typically using HMAC-SHA256, and your endpoint recomputes the signature and compares it before trusting the event.
Technical Architecture & Deep-Dive
Webhook endpoints are public URLs, so anyone can send fake events, such as a forged payment succeeded notification. Signatures prevent this. Stripe, Paddle, Shopify, and GitHub each send a signature header computed over the raw request body and often a timestamp.
Verification must use the raw body before JSON parsing, a constant-time comparison, and a timestamp tolerance to block replay attacks. Edge runtimes support Web Crypto HMAC natively.
Key Architectural Benefits
HMAC Webhook Verification
const key = await crypto.subtle.importKey(
'raw', new TextEncoder().encode(env.WEBHOOK_SECRET),
{ name: 'HMAC', hash: 'SHA-256' }, false, ['verify']
);
const valid = await crypto.subtle.verify(
'HMAC', key, hexToBytes(signature), new TextEncoder().encode(rawBody)
);
if (!valid) return new Response('Invalid signature', { status: 401 });Implement Webhook Signature Verification at the Edge
Deploy lightweight API aggregation, edge caching, and secret injection in minutes without Docker containers or complex servers.
Frequently Asked Questions
Q:Why must I use the raw request body?
Parsing and re-serializing JSON can change whitespace or key order, producing a different signature even for a legitimate payload.
Related Architecture Concepts
A webhook is an HTTP callback: when an event occurs in one system, it sends an HTTP POST with event data to a URL you register. Instead of polling an API repeatedly for changes, your application receives updates in real time, such as payment succeeded or ticket created events.
HMAC authentication uses a hash-based message authentication code, computed from a message and a shared secret key, to prove that a request came from a holder of the secret and was not modified. The receiver recomputes the HMAC and compares it to the value sent.
Idempotency means that performing the same API operation multiple times has the same effect as performing it once. Idempotent endpoints let clients and gateways safely retry requests after timeouts without creating duplicate orders, charges, or records.