HMAC-Signed Webhooks: Building Reliable Event-Driven Pipelines

Webhooks are the backbone of modern event-driven architectures, but an HTTP endpoint that processes incoming requests without verifying their origin is a security vulnerability waiting to be exploited. HMAC-signed webhooks solve this problem elegantly, providing a cryptographically verifiable way to confirm that incoming webhook payloads came from a trusted source and weren't tampered with in transit. Understanding HMAC signatures is essential for anyone building serious webhook-based pipelines.

What Is HMAC and Why Does It Matter for Webhooks?

HMAC stands for Hash-based Message Authentication Code. It's a cryptographic technique that uses a shared secret key combined with a hash function (in AyeWatch's case, SHA-256) to generate a fixed-size "signature" of a message. The key properties that make HMAC ideal for webhook authentication are:

• Only parties with the secret key can generate a valid signature: An attacker who doesn't know your webhook secret cannot generate a valid HMAC signature, so fake payloads will fail verification.
• Any modification to the message invalidates the signature: Even changing a single character in the payload produces a completely different signature, so tampered payloads will fail verification.
• Signatures are deterministic: The same message with the same key always produces the same signature, making verification reliable and reproducible.

How AyeWatch Signs Webhooks

When AyeWatch delivers a webhook, it computes an HMAC-SHA256 signature of the raw request body using your webhook secret as the key. This signature is included in the X-AyeWatch-Signature header of the request, prefixed with sha256= to indicate the algorithm used.

The raw request body, not the parsed JSON, is what gets signed. This is important for implementation: you must read the raw bytes of the request body before parsing it as JSON, then use those raw bytes for signature computation.

Implementing Verification in Node.js

In Node.js with Express, use the express.raw() middleware (not express.json()) for your webhook route, then compute and compare the HMAC:

• Import crypto from Node's standard library
• Compute crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex')
• Prepend sha256= to match AyeWatch's header format
• Use crypto.timingSafeEqual() to compare the computed signature to the header value, this prevents timing attacks

Implementing Verification in Python

In Python with Flask or FastAPI, use hmac.new(webhookSecret.encode(), rawBody, hashlib.sha256).hexdigest() and compare using hmac.compare_digest() (the constant-time comparison equivalent) to prevent timing attacks.

Idempotency: Handling Duplicate Deliveries

Even with reliable HMAC-signed webhooks, your endpoint will occasionally receive the same webhook more than once. Network timeouts, retries, and edge cases in delivery infrastructure can cause duplicate deliveries. The standard solution is idempotency keys: AyeWatch includes a unique alert ID in each webhook payload. Before processing, check whether you've already processed an alert with that ID.

Handling Webhook Failures Gracefully

Best practices for reliable webhook pipelines:

• Acknowledge receipt immediately (return 200 quickly), then process asynchronously in a background queue
• Use a message queue (SQS, RabbitMQ, Redis Queue) as a buffer between your webhook endpoint and processing logic
• Monitor your webhook endpoint's availability and error rates
• Implement alerting when webhook processing failures spike

Basically,

HMAC-signed webhooks are a security fundamental for any production event-driven pipeline. The implementation is straightforward once you understand the pattern, and the security benefits are significant. Combined with idempotency handling and proper error management, HMAC verification is the foundation of reliable, secure webhook integrations.

Ready to build? The AyeWatch API documentation includes complete webhook verification examples. Access to webhooks is included in the Pro+ plan. Get started today.