This is a searchable reference for SendGrid (Twilio) Event Webhook event types — every event value SendGrid POSTs to your endpoint, grouped into delivery, engagement, and account categories. Each entry lists the key JSON fields the event carries and what it means, so you can build a reliable handler that updates send status, suppresses bad addresses, and records engagement.
How it works
SendGrid POSTs an array of JSON objects to your configured webhook URL. Every object shares common fields and adds event-specific ones:
{
"email": "[email protected]",
"timestamp": 1717689600,
"event": "bounce",
"sg_event_id": "abc123",
"sg_message_id": "msg.0001",
"reason": "550 5.1.1 user unknown",
"type": "bounce"
}Events fall into three categories. Delivery events (processed, deferred, delivered, bounce, dropped) track the lifecycle from acceptance into SendGrid through to the receiving server. Engagement events (open, click, spamreport, unsubscribe, group_unsubscribe, group_resubscribe) track what the recipient did. The bounce event’s type field (bounce vs blocked) and the reason field tell you whether the failure was hard (permanent) or soft (temporary).
Event decision matrix
Use this as a guide for what to do when each event arrives:
| Event | Action |
|---|---|
processed | Update send status to “queued” |
delivered | Update send status to “delivered” |
deferred | Log and monitor; no action needed unless it transitions to bounce |
bounce (type=bounce) | Hard bounce — suppress address immediately, do not retry |
bounce (type=blocked) | Soft bounce — log; retry limits are SendGrid’s responsibility |
dropped | Already suppressed — verify the suppression list entry |
open | Increment open count; note: inflated by proxies |
click | Record the url field; note: link scanners fire clicks too |
spamreport | Suppress immediately; review sending practices |
unsubscribe | Remove from all future marketing sends |
group_unsubscribe | Remove from the specific unsubscribe group only |
group_resubscribe | Re-add to the specific group if your UX allows re-opt-in |
Building a reliable webhook handler
Idempotency: SendGrid may deliver the same event more than once. Dedupe on
sg_event_id before applying any state change — use it as a unique key in your
events table.
Batch processing: SendGrid batches events and POSTs arrays, not individual objects. Your endpoint must parse a JSON array, not a single object.
Signature verification: SendGrid signs webhook payloads with a public key.
Verify the X-Twilio-Email-Event-Webhook-Signature header to reject spoofed
requests before processing any payload.
SMTP response codes in reason: for bounce events, the reason field
contains the SMTP response from the receiving server. A 5xx code is a permanent
failure (hard bounce); a 4xx is temporary. Parse the leading digit to automate
the distinction rather than relying only on the type field.
Open and click inflation
Open tracking fires when the 1x1 pixel image loads, and click tracking fires when a rewritten link is followed. Both are inflated by:
- Email clients and proxies that pre-fetch images for spam filtering or to warm up links before displaying them.
- Link-scanning security tools that follow every link in an email to check for malicious content.
Never gate critical logic (like a “confirm your account” flow) on an open event alone. Use open and click rates as trends across campaigns, not as guarantees of human engagement on individual messages.
Everything runs in your browser; nothing is uploaded.