HMAC webhook signature verification for email events

Your agent just received an email.received webhook. Or did it? Without HMAC signature verification, there's no way to distinguish a legitimate email event from a spoofed payload hitting the same endpoint. Every unverified webhook is a door you forgot to lock.

This matters more for email events than most other webhook types. A fake email.bounced event can trick your agent into blacklisting a valid contact. A spoofed email.received event can inject content your agent trusts and acts on without question. If your agent processes email programmatically, HMAC verification is the minimum viable security boundary.

LobsterMail signs every webhook payload with HMAC-SHA256 and returns the secret exactly once at creation time. Get your agent its own inbox, paste the setup instructions, and your agent will have HMAC-verified email events running in minutes.

How to verify an HMAC webhook signature for email events#

1. Capture the raw, unparsed request body before any JSON parsing middleware runs.
2. Extract the provider-supplied signature from its designated HTTP header (e.g., X-Webhook-Signature).
3. Recompute a fresh HMAC-SHA256 digest using your stored secret key and the raw body.
4. Hex-encode both the computed digest and the extracted signature.
5. Compare them using a constant-time (timing-safe) equality function.
6. Return HTTP 200 on match, or HTTP 401 and discard the event on mismatch.

Every email event type follows the same verification flow. Whether the payload carries a bounce notification, a new inbound message, or a quarantine alert, the signature covers the full body. Verify once at the boundary, then trust the data downstream.

What HMAC actually does#

HMAC (Hash-based Message Authentication Code) combines a cryptographic hash function with a secret key to produce a fixed-length signature. The webhook provider computes this signature over the raw request body before sending. Your server recomputes it on arrival using the same secret. If both signatures match, you know two things: the payload hasn't been modified in transit, and it was sent by someone who holds the secret key.

For email events, the threat model is concrete. Your agent's webhook URL is a public HTTP endpoint. Anyone who discovers it through logs, network inspection, or brute force can POST arbitrary JSON to it. Without HMAC verification, your agent has no way to distinguish these fake payloads from real ones. With it, every spoofed request fails signature validation and gets rejected before your agent ever touches the data.

Implementing verification in Node.js#

Here's a complete Express middleware for verifying HMAC signatures on incoming email webhooks:

const crypto = require('crypto');

function verifyWebhookSignature(secret) {
  return (req, res, next) => {
    const signature = req.headers['x-webhook-signature'];
    if (!signature) {
      return res.status(401).json({ error: 'Missing signature header' });
    }

    const computed = crypto
      .createHmac('sha256', secret)
      .update(req.rawBody)
      .digest('hex');

    const trusted = Buffer.from(computed, 'utf8');
    const untrusted = Buffer.from(signature, 'utf8');

    if (trusted.length !== untrusted.length ||
        !crypto.timingSafeEqual(trusted, untrusted)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    next();
  };
}

One thing most tutorials skip: you need the raw, unparsed request body. Configure Express to preserve it during JSON parsing:

app.use(express.json({
  verify: (req, _res, buf) => {
    req.rawBody = buf;
  }
}));

If Express has already parsed and re-serialized the JSON, the byte-level representation may differ from what the provider signed. Whitespace or key ordering can change silently. The HMAC won't match, and you'll spend hours debugging a "broken" webhook that's actually a parsing order problem.

Implementing verification in Python#

import hmac
import hashlib

def verify_signature(payload_body: bytes, secret: str, signature_header: str) -> bool:
    computed = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(computed, signature_header)

Python's hmac.compare_digest handles constant-time comparison for you. Pass the raw request body as bytes, not a decoded string. In Flask, that means request.get_data(). In FastAPI, use await request.body() before any Pydantic model parsing runs.

Why timing-safe comparison matters#

A regular === or == comparison short-circuits on the first mismatched character. An attacker can measure response time differences across thousands of requests to reconstruct a valid signature one byte at a time. This is called a timing attack, and it isn't theoretical.

crypto.timingSafeEqual in Node.js and hmac.compare_digest in Python compare every byte regardless of where a mismatch occurs. The response time stays constant whether the first character is wrong or the last one is.

Handling verification failures#

When HMAC verification fails, return HTTP 401 and stop processing immediately. Don't return 200 and silently ignore the payload. Some providers interpret 200 as successful delivery and won't retry, which means you'll miss legitimate events during a temporary key mismatch. Returning 500 is also wrong: it signals a server error and the provider may keep retrying a potentially malicious payload.

Log the failure with enough context to investigate: timestamp, source IP, the event type claimed in the payload. But don't log the raw body. A spoofed payload might contain data designed to pollute your logs or trigger downstream processing if someone reviews them later.

For agents processing high volumes of email events, track verification failure rates over time. A sudden spike usually means either your secret rotated without updating the endpoint, or someone is actively probing your webhook URL. Both require different responses. If you're thinking about the broader security picture, we wrote about whether your agent's email setup is actually secure.

Replay protection beyond HMAC#

HMAC proves authenticity and integrity. It does not prevent replay attacks. An attacker who intercepts a valid signed payload can resend it an hour later, and the signature will still verify. To defend against replays, check the timestamp in the payload and reject anything older than a few minutes:

const eventTime = new Date(payload.timestamp);
const now = new Date();
const fiveMinutes = 5 * 60 * 1000;

if (Math.abs(now - eventTime) > fiveMinutes) {
  return res.status(401).json({ error: 'Stale event' });
}

Combine timestamp checks with idempotency keys. If your agent has already processed event eml_abc123, don't process it again even when the signature is valid. Duplicate delivery notifications happen often with email webhooks, and without deduplication your agent might send the same reply twice. We covered related architectural tradeoffs in our post on webhooks vs polling for agent email.

How email providers differ#

Not every email provider signs webhooks the same way. Header names, encoding formats, and what gets signed all vary across the industry:

If your agent receives events from multiple providers, abstract the verification pattern (extract header, compute digest, compare) and swap in provider-specific details. LobsterMail's approach of SHA-256 with hex encoding over the raw body follows the most common convention and is the simplest to implement.

When you create a LobsterMail webhook, the secret is returned exactly once:

const webhook = await lm.createWebhook({
  url: 'https://your-agent.example.com/hooks/email',
  events: ['email.received', 'email.bounced', 'email.quarantined'],
});

// Store this immediately — it won't be shown again
const secret = webhook.secret; // whsec_...

Store that whsec_ value in your environment variables or a secrets manager the moment you receive it. If you lose it, you'll need to delete the webhook and create a new one.

After verification passes#

Once the signature checks out, parse the JSON, route by event type, and let your agent act on the data. The verification middleware sits at the boundary so your business logic never needs to question whether the payload is authentic.

For agents that manage their own inbox, this boundary is the single most important line of defense. Your webhook URL is a public surface that anyone can hit. HMAC verification is what turns it from an open target into a trusted channel.

Start with SHA-256, timing-safe comparison, and timestamp validation. Add idempotency tracking once your agent handles enough volume for duplicate events to become a real problem. That combination covers the threat model for nearly every email webhook integration you'll build.