SendGrid webhooks
SendGrid webhooks are HTTP POSTs SendGrid sends to your URL: the Event Webhook reports what happens to email you send, and Inbound Parse delivers email you receive.
These pages cover the Event Webhook, which reports on email you send. Inbound Parse, which posts email you receive as multipart/form-data, has no event types and is covered in the Production guide.
How SendGrid webhooks work
The Event Webhook saves you polling for what happened to your mail. SendGrid pushes deliverability events such as delivered and bounce, engagement events such as open and click, and account status changes in nearly real time. Events arrive in batches rather than one per request: each server posts within about 30 seconds or when its batch reaches 768 KB, so high volume can mean tens or even hundreds of posts per second.
Each POST body is a JSON array, so read event on each element, and expect one batch to mix event types. sg_event_id identifies the event and sg_message_id the message, and custom arguments you set when sending appear as top-level keys on each event. SendGrid's docs name no version header or payload version field.
Key facts
x-twilio-email-event-webhook-signature Not every delivery is signed: check your setup.
{timestamp}{raw body} The X-Twilio-Email-Event-Webhook-Timestamp value as sent, then the body's raw bytes, with nothing between them. The signature covers a SHA-256 hash of that.
Setting up SendGrid webhooks
- In the SendGrid UI, go to Settings, then Mail Settings, then Event Webhooks under Webhook Settings, and select Create new webhook. Set the Post URL and Actions to be posted.
POST /v3/user/webhooks/event/settingsdoes the same. - Your plan sets how many webhooks you can have. Each has its own URL, actions and security settings, so you can send different events to different places.
- Select Test Your Integration to POST a JSON array of example events, or call
POST /v3/user/webhooks/event/test. To reach your own machine, use a tunnel such as the Hookdeck CLI. - SendGrid's docs describe no way to resend an event yourself, so log what you receive.
Delivery behaviour
not documented SendGrid publishes no limit, so return a 2xx quickly Retries up to 24 hours at increasing intervals after any non-2xx, counted from when the event occurred After retries no resend SendGrid's docs describe no way to resend an event yourself Duplicates possible deduplicate each array element on sg_event_id Known failure modes
From Hookdeck's SendGrid guide →-
Duplicate events
SendGrid can post the same event more than once, and one POST holds many events. Loop over the array and deduplicate each element on
Handle duplicates →sg_event_id, not the whole request. -
Out-of-order events
SendGrid's docs promise no delivery order, and it builds batches per server, so don't assume an
Handle ordering →openarrives after itsdelivered. Comparetimestampand never move a message back to an earlier state. -
Events missed after an outage
SendGrid retries each event for up to 24 hours after it occurred, then stops, and its docs describe no way to resend. Keep the endpoint available and store what you receive.
Retries and lost events → -
Spam reports missed by event name
The reference's
Choosing events →eventproperty listsspam report, but its example payload saysspamreport. Matchspamreport, and use underscores forgroup_unsubscribeandgroup_resubscribe.
SendGrid webhook best practices
- Turn on signing and verify every request. Signing is off until you enable it for a webhook. Without it or OAuth, anyone who finds your Post URL can send fake events.
- Return a 2xx fast and queue the batch. SendGrid publishes no timeout and retries anything other than a 2xx, and high volume can bring hundreds of posts per second.
- Deduplicate each event, not each request.
Loop over the array and track
sg_event_id, because an error partway through a batch can bring events you already handled back. - Accept events in any order.
SendGrid's docs promise no order. Compare
timestampand rank your states, so a lateprocessedcan't overwritedelivered. - Select only the actions you process.
Each action adds traffic.
openandclickalso need Open Tracking and Click Tracking turned on. - Keep your own copy of events. Retries stop 24 hours after an event occurs, and the Email Activity Feed keeps 30 days of events only with a paid add-on.
Common SendGrid webhook events
Delivery
delivered | Receiving mail server accepts the message |
bounce | Receiving server refuses the message, as a hard bounce or a block |
dropped | SendGrid drops the message, for example for a previously bounced address |
deferred | Receiving server temporarily refuses the message |
Engagement
open | HTML message is opened, including Apple Mail Privacy Protection opens |
click | Recipient clicks a tracked link |
List health
spamreport | Recipient reports the message as spam |
unsubscribe | Recipient opts out of all your email |
group_unsubscribe | Recipient leaves a single unsubscribe group |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
engagement | 6 | 6 |
delivery | 5 | 5 |
1 more resource, including Other SendGrid events. All 12 events →
In this hub
| Webhook events → | Every covered SendGrid event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to SendGrid events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks |
Don't lose SendGrid events to a long outage.
Hookdeck Event Gateway accepts every SendGrid POST, verifies its signature, queues it and retries to your service on your schedule, with a log you can replay from.