# 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](/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#inbound-parse).

Agent skill: `npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks` ([details](https://hookdeck.com/webhooks/sendgrid/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [SendGrid's official docs](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/event).

[Overview](https://hookdeck.com/webhooks/sendgrid) · [Webhook events (12)](https://hookdeck.com/webhooks/sendgrid/events) · [MCP events](https://hookdeck.com/webhooks/sendgrid/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/sendgrid/verify) · [Production guide](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/sendgrid/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `x-twilio-email-event-webhook-signature` Not every delivery is signed: check your setup. | [SendGrid docs](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features) |
| Scheme | `ECDSA` Asymmetric: verify with the vendor's public key. | [SendGrid docs](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features) |
| Signed material | `{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. | [SendGrid docs](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features) |
| How events are identified | `event field in the body` | [SendGrid docs](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/event) |
| Body format | `JSON` Content type: application/json. | [SendGrid docs](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook) |
| Send timestamp | `x-twilio-email-event-webhook-timestamp` | [SendGrid docs](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/sendgrid/skill) |

[Verify SendGrid webhooks](https://hookdeck.com/webhooks/sendgrid/verify)

## 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.

## 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/settings` does 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](/docs/cli).
- SendGrid's docs describe no way to resend an event yourself, so log what you receive.

## Delivery behaviour

- **Timeout:** not documented. SendGrid publishes no limit, so return a 2xx quickly. [Guide](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** up to 24 hours. at increasing intervals after any non-2xx, counted from when the event occurred. [Guide](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** no resend. SendGrid's docs describe no way to resend an event yourself. [Guide](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#retries)
- **Duplicates:** possible. deduplicate each array element on `sg_event_id`. [Guide](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#duplicates)

## Known failure modes

1. **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 `sg_event_id`, not the whole request. [Handle duplicates](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#duplicates)
2. **Out-of-order events.** SendGrid's docs promise no delivery order, and it builds batches per server, so don't assume an `open` arrives after its `delivered`. Compare `timestamp` and never move a message back to an earlier state. [Handle ordering](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#ordering)
3. **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](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#retries)
4. **Spam reports missed by event name.** The reference's `event` property lists `spam report`, but its example payload says `spamreport`. Match `spamreport`, and use underscores for `group_unsubscribe` and `group_resubscribe`. [Choosing events](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#choosing-events)

From [Hookdeck's SendGrid guide](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts).

## SendGrid webhook best practices

- **[Turn on signing and verify every request](https://hookdeck.com/webhooks/sendgrid/verify).** 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](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#duplicates).** 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](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#ordering).** SendGrid's docs promise no order. Compare `timestamp` and rank your states, so a late `processed` can't overwrite `delivered`.
- **[Select only the actions you process](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#choosing-events).** Each action adds traffic. `open` and `click` also need Open Tracking and Click Tracking turned on.
- **[Keep your own copy of events](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/sendgrid/events#delivered): Receiving mail server accepts the message
- [bounce](https://hookdeck.com/webhooks/sendgrid/events#bounce): Receiving server refuses the message, as a hard bounce or a block
- [dropped](https://hookdeck.com/webhooks/sendgrid/events#dropped): SendGrid drops the message, for example for a previously bounced address
- [deferred](https://hookdeck.com/webhooks/sendgrid/events#deferred): Receiving server temporarily refuses the message

### Engagement

- [open](https://hookdeck.com/webhooks/sendgrid/events#open): HTML message is opened, including Apple Mail Privacy Protection opens
- [click](https://hookdeck.com/webhooks/sendgrid/events#click): Recipient clicks a tracked link

### List health

- [spamreport](https://hookdeck.com/webhooks/sendgrid/events#spamreport): Recipient reports the message as spam
- [unsubscribe](https://hookdeck.com/webhooks/sendgrid/events#unsubscribe): Recipient opts out of all your email
- [group_unsubscribe](https://hookdeck.com/webhooks/sendgrid/events#group_unsubscribe): Recipient leaves a single unsubscribe group

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [engagement](https://hookdeck.com/webhooks/sendgrid/events#resource-engagement) | 6 | 6 |
| [delivery](https://hookdeck.com/webhooks/sendgrid/events#resource-delivery) | 5 | 5 |

1 more resource. [All 12 events](https://hookdeck.com/webhooks/sendgrid/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/sendgrid/events): Every covered SendGrid event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/sendgrid/mcp-events): How an agent subscribes to SendGrid events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/sendgrid/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/sendgrid/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/sendgrid/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks`
---

Not affiliated with SendGrid. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/sendgrid.json) · [Report a correction](https://hookdeck.com/contact)
