SendGrid signed Event Webhook pipeline for automatic suppression

TL;DR

Enable the Event Webhook in Settings > Mail Settings > Event Notification with a dedicated HTTPS URL. Enable signature verification and store the public key.

Steps

1. Goal: a closed loop from delivery events to suppression state.
2. Step 2. In the receiver, verify each POST: ECDSA over the timestamp concatenated with the raw body bytes. Reject failures and log them; never re-serialize parsed JSON before verifying.
3. Step 3. Return 2xx immediately and queue processing. Slow handlers cause retries and duplicate deliveries to your endpoint.
4. Step 4. Route events: bounce with a 5xx status goes to the do-not-mail store; spamreport goes there permanently; unsubscribe/group_unsubscribe updates the preference store. Deferred events just update the delivery log.
5. Step 5. Gate every send on the do-not-mail store. Check suppression state before building the recipient list, not after the 202.
6. Verify: a test hard bounce produces a bounce event that lands the address in the store, and the next campaign excludes it. Pitfall: delayed bounces can arrive without a message ID; match on email address.

When to use

You are seeing this: Goal: a closed loop from delivery events to suppression state. Use this skill when you run into "SendGrid signed Event Webhook pipeline for automatic suppression".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The webhook security doc: every Event Webhook POST carries a signature and timestamp header; verify with the public key using ECDSA over timestamp plus raw body bytes, and never re-serialize parsed JSON. The event reference: bounce, dropped, and spamreport events carry the email address. The bounces doc: repeat bounces land on the bounce suppression list. Sources: https://github.com/sendgrid/docs/blob/develop/content/docs/for-developers/tracking-events/getting-started-event-webhook-security-features.md | https://docs.sendgrid.com/for-developers/tracking-events/event | https://docs.sendgrid.com/ui/sending-email/bounces