SendGrid's Event Webhook sends real-time notifications about your email delivery events, including deliveries, opens, clicks, bounces, and spam reports. These webhooks are crucial for email deliverability monitoring.
SendGrid webhooks are HTTP POST requests that SendGrid sends to your server when specific events occur in your account. Rather than continuously polling the SendGrid API for updates, webhooks deliver real-time notifications the moment something happens — a payment completes, a user signs up, a deployment finishes, or any other tracked event.
Debugging these webhooks can be challenging because they originate from SendGrid's servers, not your browser. You can't simply open DevTools to inspect them. That's where WebhookVault comes in — capture every SendGrid webhook, inspect the full payload and headers, and replay them to your local development server.
| Event | Description |
|---|---|
| delivered | Fired when the receiving server accepts your email |
| bounce | Fired when the receiving server rejects your email |
| open | Fired when a recipient opens your email (if tracking is enabled) |
| click | Fired when a recipient clicks a link in your email |
Follow these steps to start capturing and debugging SendGrid webhooks using WebhookVault.
Sign up for a free WebhookVault API key and create an endpoint to capture SendGrid webhooks.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"name": "SendGrid Webhooks"}'
# Response:
# {"url": "https://webhookvault.anethoth.com/hook/abc123", "inspect_url": "https://webhookvault.anethoth.com/inspect/abc123"}Go to SendGrid Dashboard > Settings > Mail Settings > Event Webhook Enter your WebhookVault endpoint URL Select the events you want to receive (delivered, bounced, opened, etc.) Enable the Event Webhook and save
Once SendGrid sends a webhook, you can inspect every detail through the WebhookVault API or web inspector.
curl https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests \
-H "Authorization: Bearer wv_your_key"
# Returns all captured SendGrid webhook requests with full headers, body, and metadataReplay any captured SendGrid webhook to your local development server for testing.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests/1/replay \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "http://localhost:3000/webhook"}'
# The original SendGrid webhook is replayed to your local serverHere is an example of a typical SendGrid webhook payload. Use WebhookVault to capture real payloads from your SendGrid account for accurate testing.
[
{
"email": "[email protected]",
"event": "delivered",
"sg_event_id": "ZHJvcC0xMDk5NDkxOS1MUnpYb",
"sg_message_id": "14c5d75ce93.dfd.64b469.filter0001",
"smtp-id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"timestamp": 1706000000,
"response": "250 OK"
}
]Here are the most common issues developers encounter when working with SendGrid webhooks, and how to resolve them.
SendGrid batches events and sends them as a JSON array. Your handler must parse an array, not a single object.
Enable Signed Event Webhook Requests in SendGrid settings and verify the X-Twilio-Email-Event-Webhook-Signature header.
SendGrid may send duplicate events. Use the sg_event_id field for deduplication.
Open and click tracking must be enabled in SendGrid settings. Open tracking uses a pixel and may not fire for all email clients.
SendGrid webhooks are HTTP callbacks that SendGrid sends to your server when specific events occur. Instead of polling the SendGrid API for changes, webhooks push real-time notifications to your application, making your integration more efficient and responsive.
Use WebhookVault to capture SendGrid webhooks in the cloud, then replay them to your localhost. Create a WebhookVault endpoint, configure SendGrid to send webhooks to it, and use the replay API to forward captured requests to http://localhost:3000/webhook (or your local port).
Most webhook providers, including SendGrid, sign their webhook payloads to prove authenticity. Check the SendGrid documentation for the specific signature header and verification algorithm. Use WebhookVault to capture and inspect the raw headers to debug signature verification issues.
Unlike ngrok, WebhookVault captures and stores every webhook request with full headers and payloads. You can replay any SendGrid webhook to your local server as many times as needed, inspect historical requests, and share webhook data with your team. No tunnel to maintain or port to expose.
Create a free WebhookVault endpoint in seconds. Capture, inspect, and replay SendGrid webhooks with zero configuration.
Get Free API Key