# SendGrid webhooks in production: duplicates, ordering, retries and timeouts

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

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](#inbound-parse), which posts email you receive, has its own section. What SendGrid sends and how it's signed is on the [SendGrid webhooks](/webhooks/sendgrid) overview, every event type is on [SendGrid webhook events](/webhooks/sendgrid/events), and signature verification code is on [Verify SendGrid webhooks](/webhooks/sendgrid/verify).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#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](#duplicates) | Deduplicate each array element on `sg_event_id` | Drops a repeated POST before it reaches your handler |
| [Ordering](#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](#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](#choosing-events) | Select only the actions you process; match `spamreport` | Filters and routes POSTs by their contents |
| [Testing](#testing) | Use Test Your Integration, then real email through a tunnel | Forwards to localhost and replays past events |
| [Other limits](#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](#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 {#timeouts}

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:**

1. Verify the signature and return 200 straight away.
2. Push the batch onto a queue (SQS, RabbitMQ or Redis) and process it in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
3. 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 {#duplicates}

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:**

1. Track processed `sg_event_id` values 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](/webhooks/guides/implement-webhook-idempotency).
2. Don't use `sg_message_id` as the key. It identifies the message, which has many events.
3. 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.
4. Handle a missing id. SendGrid's legacy Marketing email unsubscribe example has no `sg_event_id`.

```javascript
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](/docs/deduplication) 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 {#ordering}

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](/webhooks/guides/webhook-ordering-why-its-hard-and-how-to-handle-it).

**Fix it in your handler:**

1. Group events by `sg_message_id` and compare `timestamp`, which says when the event occurred. Delayed and asynchronous bounces don't carry `sg_message_id`, so you may need `smtp-id` and `email` to match those.
2. 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.
3. Rank your states so a late `processed` can't overwrite `delivered`, 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 {#retries}

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:**

1. Run webhook endpoints on high-availability infrastructure, and alert on your own error rate and on gaps in expected traffic.
2. Store each raw batch as it arrives. SendGrid itself suggests the Event Webhook for keeping event data to meet your own retention needs.
3. If you have the add-on, reconcile against the Email Activity API after a long outage. See [dead letter queues](/webhooks/guides/dead-letter-queues-webhook-reliability) 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](/docs/retries) automatically, manually or in bulk once you recover.

## Choosing which SendGrid events to listen to {#choosing-events}

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](/webhooks/sendgrid/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:**

1. Match `spamreport`. The reference's `event` property lists `spam report`, but the example payload in that same reference says `spamreport`. Group events use underscores: `group_unsubscribe` and `group_resubscribe`.
2. Read `type` on a `bounce`. `bounce` is a permanent denial and `blocked` is a temporary one that the receiving server might accept later, so don't suppress an address on a block.
3. Read `sg_machine_open` on an `open`. When it's `true`, Apple Mail Privacy Protection generated the event, so it doesn't show that a person read the message.
4. 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](/docs/filters) match on request contents, including arrays, and one source can feed several [connections](/docs/connections). A filter passes or blocks a whole POST, so a mixed batch reaches every destination whose filter it matches. A [transformation](/docs/transformations) can trim the array to the events each destination handles.

## Testing and debugging SendGrid webhooks locally {#testing}

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:**

1. 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.
2. Send real email and follow a message from `processed` to `delivered` to `open` and `click`. Then try an address that bounces.
3. Send a bulk run to see real batch sizes, and take your endpoint offline for a while to watch the retries.
4. Keep fixtures of multi-event batches for your tests. [SendGrid webhook events](/webhooks/sendgrid/events) has sample payloads to start from.

**With Event Gateway:** The [Hookdeck CLI](/docs/cli) receives webhooks on your machine without a public server, and you can replay past events with one click.

## Other SendGrid webhook limits {#other-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}

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:**

1. 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.
2. 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-Signature` and `X-Twilio-Email-Event-Webhook-Timestamp` headers, and the policy response gives you the public key.
3. Verify against the raw request body. SendGrid warns that frameworks which parse multipart data and separate file uploads can break validation.
4. 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](/docs/sources#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.