Test and debug SendGrid Event Webhooks

Pointing the Event Webhook at a test URL

Create a URL above, then go to SendGrid → Settings → Mail Settings → Event Webhooks. Create a webhook, paste the URL, tick the event types you want, and enable Signed Event Webhook Requests — that is what produces the signature headers and reveals the verification key.

SendGrid gives you a Test Your Integration button, which sends one synthetic event of each selected type. That is the fastest way to see the shape. For real events, send yourself a message through the API and then open it and click a link.

The body is an array, and that is the whole story

[
  { "email": "buyer@example.com", "event": "delivered", "sg_event_id": "...", "smtp-id": "<...>" },
  { "email": "buyer@example.com", "event": "open", "sg_event_id": "..." },
  { "email": "bounce@example.com", "event": "bounce", "type": "blocked", "reason": "..." }
]

Nearly every SendGrid integration bug traces back to this. The handler is written the way handlers for every other provider are written — read body.event, switch on it — and because JavaScript returns undefined for a missing property on an array rather than throwing, it fails without a single error in the logs.

const events = await request.json();
for (const event of events) {
  await handle(event); // one at a time, and never let one throw out of the loop
}
return new Response(null, { status: 200 });

The for loop and the unconditional 200 are both load-bearing. SendGrid retries the entire batch on a non-2xx, so one bad row otherwise causes the other 199 events to be delivered again — and again.

Batching is not optional

You cannot ask for one event per request. High-volume accounts routinely see hundreds of events in a single POST, which is why the timeout is 30 seconds rather than 5. Design the handler to enqueue rather than to process inline, and the batch size stops mattering.

Verifying the signature

Two headers arrive together:

X-Twilio-Email-Event-Webhook-Signature: MEUCIQ...
X-Twilio-Email-Event-Webhook-Timestamp: 1750000000

The signed data is the timestamp followed immediately by the raw body, with no separator. The signature is DER-encoded ECDSA over P-256, base64-encoded. The dashboard’s “verification key” is a base64 public key.

const signed = timestampHeader + rawBody;
const ok = crypto.verify('sha256', Buffer.from(signed), publicKeyPem, Buffer.from(sigHeader, 'base64'));

This is genuinely different from every HMAC scheme on this site, and it is better: the key on your server cannot forge a signature, so a compromised web server does not let an attacker mint fake events. It also means there is nothing to paste into a signature-verification tool that only speaks HMAC, including this one. SendGrid’s official SDKs each ship an EventWebhook helper that does the four lines above with the DER-to-PEM conversion handled.

Check the timestamp as well — the signature does not expire on its own.

Reading the events

sg_message_id identifies the message, sg_event_id identifies the event. Deduplicate on the second one; grouping by the first is how you assemble a timeline for one send.

bounce needs care. A type of bounce means the address is bad and should be suppressed permanently. A type of blocked means the receiving server refused this message for reputational or content reasons — the address is fine and suppressing it loses a real recipient. reason carries the SMTP response, which is where the actual explanation lives.