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.

12 events covered

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

Signature header
x-twilio-email-event-webhook-signature

Not every delivery is signed: check your setup.

Scheme
ECDSA

Asymmetric: verify with the vendor's public key.

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.

How events are identified
event field in the body
Body format
JSON

Content type: application/json.

Send timestamp
x-twilio-email-event-webhook-timestamp
Agent skill
npx skills add hookdeck/webhook-skills --skill sendgrid-webhooks

Verify SendGrid webhooks →

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.
  • SendGrid's docs describe no way to resend an event yourself, so log what you receive.

Delivery behaviour

  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 →
  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 →
  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 →
  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 →

SendGrid webhook best practices

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

open · click · unsubscribe · spamreport +2

6 6
delivery

processed · delivered · bounce · deferred +1

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.

Not affiliated with SendGrid. Facts are compiled from public sources and linked inline.