SendGrid webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems SendGrid webhooks cause in production and how to handle each one. Most of it is about the Event Webhook, which reports what happens to email you send. Inbound Parse, which posts email you receive, has its own section. What SendGrid sends and how it's signed is on the SendGrid webhooks overview, every event type is on SendGrid webhook events, and signature verification code is on Verify SendGrid webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 2xx fast and queue the batch; SendGrid publishes no limit | Accepts the POST at once, then queues it for your service |
| Duplicates | Deduplicate each array element on sg_event_id | Drops a repeated POST before it reaches your handler |
| Ordering | Compare timestamp and never move a message back a state | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Stay available for the 24-hour window and keep your own copy | Accepts POSTs while your service is down and replays them |
| Choosing events | Select only the actions you process; match spamreport | Filters and routes POSTs by their contents |
| Testing | Use Test Your Integration, then real email through a tunnel | Forwards to localhost and replays past events |
| Other limits | Plan for redirects, changing IPs, plan limits and varying fields | Gives SendGrid one stable URL and fans out to many destinations |
| Inbound Parse | Return a 2xx, keep the raw body, and watch the 3-day limit | Accepts the POST while your service is down |
SendGrid webhook timeouts and slow handlers
Return a 2xx as fast as you can, then process the batch in a background job. SendGrid's docs don't publish a response timeout, so don't design around a number.
Why it happens: SendGrid retries a POST on any response other than a 2xx. Each POST can hold many events, and SendGrid says high volume can mean tens or even hundreds of posts per second, because batches are sent per server. A handler that writes to a database or calls other APIs for each event falls behind quickly, and SendGrid warns that this traffic can overload a web server that isn't configured for it.
Fix it in your handler:
- Verify the signature and return 200 straight away.
- Push the batch onto a queue (SQS, RabbitMQ or Redis) and process it in a worker. See why to process webhooks asynchronously.
- Load test the receiver at the event volume your sending produces, as SendGrid recommends.
With Event Gateway: Hookdeck accepts each SendGrid POST immediately, then queues it and delivers it to your service at a rate it can handle, with its own retries. A slow handler doesn't fail a SendGrid delivery.
Duplicate SendGrid webhooks
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.
Why it happens: SendGrid's docs say duplicates are possible and recommend deduplicating on sg_event_id. Batching makes this easy to get wrong. If your handler processes half a batch and then returns an error, the events it already handled can come back. The docs also don't say whether a retry holds the same batch, so a key for the whole request isn't enough.
Fix it in your handler:
- Track processed
sg_event_idvalues per event, using a unique constraint or a fast store with an expiry longer than the 24-hour retry window. See how to implement idempotency. - Don't use
sg_message_idas the key. It identifies the message, which has many events. - Don't cap the column at 100 characters. SendGrid's docs give that as the limit in two places and say the IDs can exceed it in a third.
- Handle a missing id. SendGrid's legacy Marketing email unsubscribe example has no
sg_event_id.
async function processBatch(events) {
for (const event of events) {
const eventId = event.sg_event_id;
// Check if we've already processed this event
if (eventId && (await redis.get(`sendgrid_event_${eventId}`))) {
continue;
}
await handleEvent(event);
// Mark as processed with a 48-hour expiry
if (eventId) {
await redis.setex(`sendgrid_event_${eventId}`, 172800, "1");
}
}
}
With Event Gateway: Hookdeck deduplicates on a request's contents, so a POST that repeats the same batch is dropped before it reaches your endpoint. It sees each POST as one event, so keep the sg_event_id check in your handler for a repeat inside a different batch.
Out-of-order SendGrid webhooks
SendGrid's docs make no promise about delivery order. Write handlers that accept events in any order, and don't assume an open arrives after its delivered.
Why it happens: SendGrid builds batches per server, and each server posts when its batch is about 30 seconds old or reaches 768 KB, so events for one message can travel in different requests. A failed POST is also retried at increasing intervals while newer events keep arriving. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Group events by
sg_message_idand comparetimestamp, which says when the event occurred. Delayed and asynchronous bounces don't carrysg_message_id, so you may needsmtp-idandemailto match those. - Treat equal timestamps as unresolved. SendGrid's standard examples are in whole seconds. One Marketing Campaigns example shows a 13-digit value, so check the unit before you compare.
- Rank your states so a late
processedcan't overwritedelivered, instead of storing whichever event came last.
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
SendGrid webhook retries and lost events
SendGrid retries a failed POST at increasing intervals for up to 24 hours after the event occurred, then stops. Keep the endpoint available and keep your own copy of what you receive.
Why it happens: Any response other than a 2xx counts as a failure. The limit is a rolling 24 hours, so each new failing event gets its own period, counted from when that event occurred. SendGrid doesn't publish the intervals. Its docs describe no way to resend an event yourself and no webhook delivery log, and they don't mention disabling an endpoint that keeps failing. The Email Activity Feed is no replacement: it keeps up to 30 days of events only with the Email Activity history add-on, which its API also requires.
Fix it in your handler:
- Run webhook endpoints on high-availability infrastructure, and alert on your own error rate and on gaps in expected traffic.
- Store each raw batch as it arrives. SendGrid itself suggests the Event Webhook for keeping event data to meet your own retention needs.
- If you have the add-on, reconcile against the Email Activity API after a long outage. See dead letter queues for the failures on your side.
With Event Gateway: Hookdeck captures every SendGrid POST while your services are down, so SendGrid's deliveries succeed and you aren't relying on its 24-hour limit. Failed events can be retried automatically, manually or in bulk once you recover.
Choosing which SendGrid events to listen to
Select only the actions you process under Actions to be posted, then check event on each array element, because one batch can mix event types.
Why it matters: Every extra action is more traffic to accept, verify and discard, and email volume makes that add up. The full list, with sample payloads, is on SendGrid webhook events. Several events also need a setting elsewhere: open needs Open Tracking, click needs Click Tracking, and the three subscription events need Subscription Tracking.
Fix it in your handler:
- Match
spamreport. The reference'seventproperty listsspam report, but the example payload in that same reference saysspamreport. Group events use underscores:group_unsubscribeandgroup_resubscribe. - Read
typeon abounce.bounceis a permanent denial andblockedis a temporary one that the receiving server might accept later, so don't suppress an address on a block. - Read
sg_machine_openon anopen. When it'strue, Apple Mail Privacy Protection generated the event, so it doesn't show that a person read the message. - Use a separate webhook to send different events to different URLs, if your plan allows more than one. The number you can have depends on your plan.
With Event Gateway: Hookdeck filters match on request contents, including arrays, and one source can feed several connections. A filter passes or blocks a whole POST, so a mixed batch reaches every destination whose filter it matches. A transformation can trim the array to the events each destination handles.
Testing and debugging SendGrid webhooks locally
Send example events with Test Your Integration, then send real email through a tunnel, because examples won't show you real batches.
Why it matters: SendGrid needs a URL it can reach, so it can't post to localhost. Test Your Integration sends a JSON array of example events with no data from your mail send, and the documented examples are one-element arrays, while real deliveries can hold many events.
How to test it:
- Select Test Your Integration on the webhook, or call
POST /v3/user/webhooks/event/test. Save the webhook first if you want to test signing, because the key pair doesn't exist until you do. - Send real email and follow a message from
processedtodeliveredtoopenandclick. Then try an address that bounces. - Send a bulk run to see real batch sizes, and take your endpoint offline for a while to watch the retries.
- Keep fixtures of multi-event batches for your tests. SendGrid webhook events has sample payloads to start from.
With Event Gateway: The Hookdeck CLI receives webhooks on your machine without a public server, and you can replay past events with one click.
Other SendGrid webhook limits
Plan for redirects, changing IP addresses, plan limits and fields that vary before they reach production.
Redirects. The Event Webhook doesn't follow redirects, so a Post URL that redirects won't receive events.
TLS. If you want encrypted posts, your URL must support TLS 1.2.
IP allowlists. SendGrid says its IP addresses often change, and blocking them is a listed cause of missing events. Verify the signature rather than filtering by IP.
Plan limits. The number of Event Webhooks depends on your plan. If you downgrade below what you have, SendGrid disables your newest webhooks automatically. Disabled webhooks still count toward the limit, and they stay disabled after you upgrade until you turn them back on. Only SendGrid's Java and Python SDKs support more than one webhook.
Fields that vary. category is a string or an array, depending on how you sent it. Custom arguments appear as top-level keys on the event, and SendGrid overwrites any that use a reserved key such as event or email. account_status_change carries only event, sg_event_id, timestamp and type, so a handler that assumes email breaks on it.
Personal data. SendGrid doesn't treat categories and unique arguments as personal data, and says they generally can't be redacted or removed. Keep personal data out of them.
OAuth tokens. If you secure the webhook with OAuth 2.0, SendGrid caches the access token. When it expires, return a 4xx with invalid_token in the body, which makes SendGrid fetch a new token and retry. invalid_request and insufficient_scope do the same.
With Event Gateway: Hookdeck gives SendGrid one stable URL that doesn't redirect, absorbs spikes in its queue, and sends the events from one webhook to as many destinations as you need.
SendGrid Inbound Parse
Inbound Parse is a separate webhook. It posts email received at your domain, so it has no event field or event types, and the sections above don't apply to it. Return a 2xx quickly, and read the raw body before your framework parses it.
How it differs: Each POST is multipart/form-data with fields such as from, to, subject, text, html, envelope and attachments, and the whole message can be up to 30 MB. SendGrid queues and retries a POST that gets a 5xx. It drops a message it still can't deliver after 3 days, and it doesn't notify you first. Like the Event Webhook, it doesn't follow redirects.
Set it up safely:
- Point an MX record for a dedicated hostname at
mx.sendgrid.net, with priority 10, and add the host and URL under Settings > Inbound Parse. The domain must be authenticated. - To secure it, create a security policy with the API and attach it to the Parse setting. With signing on, requests carry the same
X-Twilio-Email-Event-Webhook-SignatureandX-Twilio-Email-Event-Webhook-Timestampheaders, and the policy response gives you the public key. - Verify against the raw request body. SendGrid warns that frameworks which parse multipart data and separate file uploads can break validation.
- Check how you read attachments. Unless you turn on POST the raw, full MIME message, SendGrid URL encodes the message but not its attachments, and code that reads only URL-encoded content can drop them.
With Event Gateway: Hookdeck accepts multipart requests, and it accepts each POST while your service is down, so SendGrid's 3-day limit doesn't drop mail during an outage.
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.