How to Verify an Email Webhook Signature Before Trusting a Bounce

A bounce event usually triggers one of two actions: add the address to a suppression list, or increment a reputation counter that eventually pauses sending to that domain. Both are sticky. A suppression list entry that was never real quietly removes a paying customer from every future campaign until someone audits it by hand. Reputation damage is harder still, because inbox providers score your domain and IP over time, and Yahoo asks senders to keep complaint rates below 0.3% while also honoring unsubscribes within two days (Yahoo Sender Hub). Gmail applies the same 0.3% threshold to spam rates reported in Postmaster Tools (Gmail sender guidelines).

The Postmaster Tools spam rate dashboard measures manual spam reports among messages that reached the inbox, not every message Gmail filtered, and it is delayed, so a clean line does not prove placement is healthy by itself (Postmaster Tools V2 explained). That matters here because a forged bounce campaign can push you toward aggressive list pruning, which shrinks engaged volume and distorts the very metrics you use to judge deliverability.

Do the arithmetic on a small campaign. Suppose you send 200,000 messages and an attacker injects 500 forged hard bounces for addresses that actually exist and engage. If those 500 addresses generated a 2% click rate and 1% of clicks convert at $40 average order value, the silent loss is 500 x 0.02 x 0.01 x $40, or $4 per campaign, every campaign, forever, until someone finds the entries. Add the support cost of even a few customers asking why they stopped receiving receipts and the endpoint hardening pays for itself quickly.

There is a second-order risk. If your bounce handler trusts unverified input and writes to a shared suppression table, an attacker who can reach the endpoint from anywhere on the internet has a cheap denial-of-service primitive against your deliverability. Gmail and Yahoo both treat sender behavior as a permanent record: Gmail states that a sender classified as a bulk sender stays classified, and enforcement escalates from temporary errors to permanent rejections for non-compliant traffic (Gmail sender guidelines FAQ). Authentication protects your outbound domain, but it does nothing for the integrity of inbound event data.

The most common bug is parsing first and verifying second. JSON parsers reorder keys, normalize whitespace and rewrite escapes, so the bytes you hash no longer match the bytes the provider signed. Capture the raw body before any middleware touches it, then verify.

A minimal Express handler looks like this. It verifies, then hands off:

const crypto = require("crypto");

const secret = process.env.EMAIL_WEBHOOK_SECRET;
const WINDOW_SECONDS = 300;

function verify(rawBody, signatureHeader, timestampHeader) {
  if (!signatureHeader || !timestampHeader) return { ok: false, why: "missing_headers" };
  const ts = Number(timestampHeader);
  if (!Number.isFinite(ts)) return { ok: false, why: "bad_timestamp" };
  const skew = Math.abs(Math.floor(Date.now() / 1000) - ts);
  if (skew > WINDOW_SECONDS) return { ok: false, why: "stale_timestamp", skew };

  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestampHeader + "." + rawBody)
    .digest("hex");

  const given = Buffer.from(signatureHeader, "utf8");
  const want = Buffer.from(expected, "utf8");
  if (given.length !== want.length) return { ok: false, why: "length_mismatch" };
  const ok = crypto.timingSafeEqual(given, want);
  return ok ? { ok: true } : { ok: false, why: "signature_mismatch" };
}

Three details carry the security. First, use crypto.timingSafeEqual, which requires equal-length buffers, so compare lengths before calling it. Second, treat the timestamp check as a separate failure with its own reason code, because stale timestamps during an incident tell you something different from a forged signature. Third, keep the raw body in memory only as long as verification needs it, and never log it at full length, since it contains recipient addresses.

Provider differences matter. SendGrid sends a JSON array of events and batches per roughly 30 seconds or 768 KB, with a 10-second response timeout and retries with exponential backoff for up to 24 hours (Hookdeck SendGrid guide). Because batching is time based, one POST can mix event types. Verify once per request, then iterate inside.

The last two rows are cheap insurance. An allowlist on event type means an injected open or click event cannot inflate engagement scores, and a domain check catches an attacker using your endpoint to insert unrelated addresses into a suppression list.

Signature verification alone does not stop replay. An attacker who captures a valid request can resend it byte for byte, and it will pass the signature check until the timestamp window closes. That window is your primary defense; keep it short. Five minutes is workable for providers with under a minute of delivery latency, and SendGrid's batching cadence means most events arrive quickly. If you see legitimate events arriving after the window, widen to ten minutes and investigate the cause rather than disabling the check.

The timestamp window has a gap: retries. SendGrid retries failed deliveries for up to 24 hours (Hookdeck SendGrid guide). A retry sent hours after the event may carry either a fresh signature with a fresh timestamp or the original signed payload, depending on the provider. If it carries the original timestamp, your window will reject a legitimate retry. The practical resolution is to accept stale timestamps only when the signature is valid and the event ID has not been processed, and to treat stale-but-valid as a distinct outcome that gets queued rather than dropped. That trades a small replay surface for not losing bounces during your own outages.

Idempotency belongs at write time, not before verification. The standard pattern is a table with a unique constraint on the provider's event ID, inserted before any side effect, with the row deleted if the handler throws so the next delivery can proceed (Hookdeck idempotency guide). Hookdeck notes that most webhook providers guarantee at least once delivery, so duplicates are expected rather than exceptional. A separate glossary on the topic draws the same distinction: retries assure delivery, idempotency keys assure that repeated requests do not duplicate effects, and the two mechanisms serve different purposes (retries and idempotency keys).

For bounce handling, the unique key should be the event ID, not the recipient address. Two different messages can bounce for the same address on the same day, and you may want both records for diagnostics even though the suppression write happens once. Structure it as two operations: insert the event row with a unique constraint (this is the idempotency gate), then apply the suppression upsert, which is naturally idempotent.

Rotation is where most verification implementations break in production. You rotate the secret, and for the next few minutes your endpoint rejects legitimate events signed with the old one, or you keep both and accidentally accept a request signed with a secret you meant to retire.

The safe pattern is a list, ordered, with an overlap period:

1. Generate the new secret in the provider dashboard and add it to your configuration as the primary, keeping the old secret as secondary.
2. Deploy, so both secrets are accepted.
3. Wait at least twice your timestamp window plus the provider's documented retry latency. For SendGrid, that retry window runs to 24 hours, so a full day of overlap is the honest answer.
4. Verify from logs that no requests have matched the secondary secret for a full window.
5. Remove the secondary and redeploy.

Record which secret matched in your logs, as a short label such as primary or secondary, never the secret itself. That single field makes step 4 mechanical instead of a guess. If your provider offers multiple active signing keys with key IDs in headers, use the key ID to select the secret and skip the trial-and-error loop entirely.

A verification failure is a security event, not a 500. Return a 400 or 401 with a short reason code, write a structured log line with the reason, the source IP, the timestamp skew and the event count if the body parsed enough to tell, and increment a counter. Alert on rate, not on single events, because scanners and misconfigured staging environments will hit your public endpoint occasionally.

Set thresholds you can defend. A reasonable starting policy: warn when verification failures exceed 10 per hour, page when they exceed 1% of total webhook volume over 15 minutes, and page immediately on any failure whose signature length matches but whose bytes do not, since that pattern suggests a deliberate attempt rather than noise. Track stale timestamps separately; a sudden run of stale-but-valid signatures usually means your own queue backed up, not an attack.

Never return a 200 to a failed verification. Some providers stop retrying on 4xx and some stop on any non-2xx after a limit, so the choice changes delivery behavior, but a 200 tells the provider the event was handled. SendGrid's 10-second timeout plus retry schedule means a fast 401 costs you nothing you wanted anyway (Hookdeck SendGrid guide).

Alert content matters as much as the alert. Include the deployed secret label, the endpoint path, the failure reason histogram for the last hour, and a link to the suppression table row count so the responder can see whether anything was written before the check was added. If you deploy through a platform where an AI agent writes the handler, keep the verification module in a small, auditable file with its own tests, and have the agent log the secret label rather than the secret.

Build a test suite around four cases, all generated locally: valid signature, one changed byte in the body, stale timestamp, and a replayed event ID. Generate the valid signature in the test itself with the same secret, so the test never depends on a captured production payload.

import hmac, hashlib, json, time

def sign(secret: str, ts: str, body: bytes) -> str:
    msg = ts.encode() + b"." + body
    return hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()

body = json.dumps([{"event": "bounce", "email": "[email protected]",
                    "sg_event_id": "test-1", "timestamp": int(time.time())}]).encode()
ts = str(int(time.time()))
sig = sign("test-secret", ts, body)

Assert four things. The valid case returns 200 and writes one suppression row. The tampered case returns 401 and writes nothing. The stale case returns 401 with reason stale_timestamp. The replay case returns 200 but the suppression table row count stays at one, and the raw event log count stays at one because the second insert hits the unique constraint.

Add two integration checks. First, a differential test that runs the body through your JSON middleware and compares JSON.stringify(parsed) to the original bytes; if they differ, your raw body capture is broken for some payload shapes, and you want to know before an escaped unicode character in a display name causes a mismatch. Second, a canary that sends a real test event from the provider to your production endpoint weekly and alerts if verification fails, which catches a rotated secret or a proxy that rewrites bodies.

Where this crosses into follow-up work, a team running several providers and a model-assisted triage step on top of the event stream ends up with per-provider adapters and a small amount of glue that normalizes event shapes. Quanta Inference gives you one OpenAI-compatible endpoint for text models if you want an agent to summarize a bounce spike or draft the incident note, with prepaid billing in US dollars (https://quantaintelligence.ai/inference).