Skip to content
HookDeploy

SendGrid webhooks

Last verified against SendGrid's documentation on September 27, 2026.

On this page ↓

SendGrid’s Event Webhook tells you what happened to the email you sent: processed, delivered, deferred, bounced, opened, clicked, marked as spam, or unsubscribed. SendGrid batches these into arrays, retries failed batches for a day, and can sign each request with an ECDSA key. Most problems come from verifying a parsed body, handling a batch as if it were one event, or a slow handler timing out on a large batch. This page covers what SendGrid sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What SendGrid sends webhooks for

GroupEventsTypical use
Deliveryprocessed, delivered, deferred, dropped, bounceTrack delivery and suppress bad addresses
Engagementopen, clickMeasure engagement
Recipient actionsspamreport, unsubscribe, group_unsubscribe, group_resubscribeKeep suppression and preference lists in sync

Each POST body is a JSON array of events. Every event has an event type, an email, a timestamp, an sg_event_id, and an sg_message_id, plus any custom arguments you attached when sending.

The Inbound Parse webhook, which turns incoming email into a multipart/form-data POST, is a separate feature with its own configuration.

How SendGrid delivers webhooks

BehaviorDetail
Method and formatPOST with a JSON array of events
Signature (optional)Signed Event Webhook: ECDSA signature in X-Twilio-Email-Event-Webhook-Signature, timestamp in X-Twilio-Email-Event-Webhook-Timestamp
Signed contentThe timestamp followed by the raw request body
OAuth (optional)SendGrid can fetch an OAuth 2.0 token from your token URL and send it as a bearer token. Independent of signing; you can use both
SuccessAny 2xx
RetriesFailed batches are retried for up to 24 hours
Deduplicationsg_event_id on each event

Common SendGrid webhook errors and how to fix them

Signature verification fails

  • The body was parsed first. SendGrid signs the raw bytes, and its docs warn that converting them to a JSON string can remove characters the signature covers. Read the raw body before any JSON middleware.
  • Wrong signed content. It’s the timestamp header followed directly by the raw body.
  • Key format. SendGrid shows the public key as a base64 string. Most libraries need it converted to a public key object first.
  • Wrong webhook. Each Event Webhook has its own key pair. Regenerating the key invalidates the old one.

Only the first event gets processed

Each POST is an array. Code that reads req.body.event as if it were a single object misses everything. Loop over the array and handle each event on its own.

Timeouts on large batches

A busy account sends large batches. If your handler does the work before responding, it can time out, and SendGrid retries the whole batch, causing duplicates. Respond with 2xx first and queue the events.

Events lost after an outage

SendGrid retries for up to 24 hours. An endpoint that’s broken for longer than that loses those events, and SendGrid can’t resend them.

Duplicate events

Retries resend whole batches. Deduplicate on sg_event_id.

Why use HookDeploy with SendGrid

Keep events past SendGrid’s retry window

HookDeploy captures every batch at Cloudflare’s edge and responds right away. If your server is down for longer than a day, the batches are still in HookDeploy for your plan’s retention period, from 7 days on Free to 365 days on Enterprise, and incidents let you bulk-replay them once it recovers.

One webhook, many systems

Send each batch to your app, a data warehouse, and an analytics pipeline in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Inspect every batch

See the exact body and headers of every delivery, alongside what your handler returned. It’s the quickest way to see which events a batch actually contained when your counts don’t add up.

Deliver to systems SendGrid can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a private data store can receive SendGrid events without a public endpoint.

Develop against real events

A tap sends a temporary copy of live SendGrid batches to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which SendGrid treats as a failed delivery and retries. Paid plans keep accepting traffic past the included volume.
  • Payload size. Large batches count against your plan’s maximum payload size, from 256 KB on Free to 100 MB on Enterprise.

Retries, replays, and duplicates

HookDeploy forwards SendGrid’s original body and signature headers unchanged. SendGrid’s helper libraries verify the signature without rejecting old timestamps, so HookDeploy retries and replays verify just like the original delivery. If you add your own timestamp age check, allow for retries and replays, or skip the check for requests carrying an auth header you inject on the destination.

Two things change the body, and so break the signature at that destination: a transformation, and a privacy filter or body key sanitization rule, which changes the stored copy used for retries and replays.

If you use SendGrid’s OAuth option, the bearer token arrives in the Authorization header, which HookDeploy redacts from stored requests. Retries and replays won’t carry it, so authenticate HookDeploy’s deliveries with a header you inject on the destination instead.

SendGrid’s retries, HookDeploy’s retries, and replays can all deliver the same events. Deduplicate on sg_event_id.

Set up SendGrid with HookDeploy

  1. In HookDeploy, create an endpoint (for example, SendGrid events) and copy its URL.
  2. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery. Add a header Authorization: Bearer YOUR_HANDLER_SECRET, and set the destination’s retries.
  3. In SendGrid, go to Settings, then Mail Settings, then Event Webhooks, and add a webhook with your HookDeploy URL and the events you want.
  4. Turn on the Signed Event Webhook and copy the verification key.
  5. Use SendGrid’s test integration option, and confirm the batch appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const publicKey = crypto.createPublicKey({
  key: Buffer.from(process.env.SENDGRID_VERIFICATION_KEY, 'base64'),
  format: 'der',
  type: 'spki',
});

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/sendgrid', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.get('x-twilio-email-event-webhook-signature') ?? '';
  const timestamp = req.get('x-twilio-email-event-webhook-timestamp') ?? '';

  const valid = crypto.verify(
    'sha256',
    Buffer.concat([Buffer.from(timestamp, 'utf8'), req.body]),  // timestamp + raw body
    publicKey,
    Buffer.from(signature, 'base64')
  );
  if (!valid) return res.status(401).send('Invalid signature');

  res.sendStatus(200);
  const events = JSON.parse(req.body.toString('utf8'));
  for (const event of events) {
    await enqueue({ eventId: event.sg_event_id, type: event.event, email: event.email, event });
  }
  // Deduplicate on eventId (sg_event_id) in your worker.
});

FAQ

How is the SendGrid Event Webhook signed?

When you enable the Signed Event Webhook, SendGrid generates an ECDSA key pair and signs each POST. The signature is in X-Twilio-Email-Event-Webhook-Signature and the timestamp in X-Twilio-Email-Event-Webhook-Timestamp. You verify the timestamp followed by the raw body against the public key SendGrid shows you.

Why does SendGrid signature verification fail?

Usually because the body was parsed and re-serialized. SendGrid's docs warn that converting the raw bytes to a JSON string can remove characters the signature covers. Other causes are using the verification key from a different webhook, or passing the base64 key string where your library expects a key object.

Does each SendGrid webhook contain one event?

No. SendGrid batches events, so each POST body is a JSON array that can hold many events for different messages. Process each item, and deduplicate on its sg_event_id.

Does SendGrid retry failed webhooks?

Yes. If your endpoint doesn't return a 2xx, SendGrid retries the batch for up to 24 hours. After that, the events in it are lost.

Does HookDeploy break SendGrid signature verification?

Not on first delivery. HookDeploy forwards the original body and signature headers unchanged. SendGrid's helper libraries don't reject old timestamps by default, so retries and replays also verify, as long as no transformation or privacy filter changed the body.

Can I use SendGrid's OAuth option with HookDeploy?

You can, but the token arrives in the Authorization header, which HookDeploy redacts from stored requests, so retries and replays won't carry it. Use the Signed Event Webhook for authenticity, and authenticate HookDeploy's deliveries with a header you inject on the destination.

Capture SendGrid webhooks free

Start free