What we do
Tools
Industries
Department
How we workLet's talk →
Home/SendGrid/SendGrid Webhook Setup, Signing and Retries
SendGrid

Setting Up a SendGrid Webhook: Events Out, Mail In, and the Signature Check

Test Your Integration came back fine, and yet real bounces aren't reaching the database. "SendGrid webhook" covers two different features: the Event Webhook, which reports what happened to mail you sent, and Inbound Parse, which posts mail people send to you. Each needs an endpoint that answers quickly and checks what it's given.

Where each SendGrid webhook lives

Event Webhook: add a Post URL, tick the events you want, and pick Signature Verification, OAuth Verification or both.

Settings Mail Settings Event Webhooks Create new webhook

Inbound Parse: add a host and the URL to post to, then point that host's MX record at mx.sendgrid.net with priority 10.

Settings Inbound Parse Add Host & URL

If your server fails: anything other than a 2xx gets retried at growing intervals for up to 24 hours after each event. After that, the event is gone.

Event Webhook and Inbound Parse do opposite jobs

Still on API keys and a first send? That part is on the SendGrid API page. This page picks up once mail is going out.

Event Webhook

What happened to mail you sent

  • Events: processed, dropped, delivered, deferred, bounce, open, click, spam report, unsubscribe, group unsubscribe and group resubscribe.
  • Arrives as a JSON array, usually several events per request.
  • Signed with ECDSA if you turn on Signature Verification.
  • Retried for up to 24 hours per event.
Inbound Parse

Mail sent to your domain

  • Each incoming message is posted with from, to, subject, body and attachments as form fields.
  • Sent as multipart/form-data, or as the raw MIME message if you tick that option.
  • Keep messages, attachments included, under 30 MB.
  • SendGrid's support notes describe Parse retries running for 72 hours.

Most apps need both: events to keep contact records honest, and Parse so a reply becomes a ticket update rather than an email nobody opens.

Writing the endpoint SendGrid posts to

  1. 1

    Reply with a 2xx straight away

    Store the request and return 200 before doing any real work. Slow handlers cause timeouts, timeouts cause retries, and retries cause duplicates.

    Watch for: redirects. The Event Webhook doesn't follow them, so register the final HTTPS address, not one that bounces to it.

  2. 2

    Verify the signature on the raw body

    With Signature Verification on, SendGrid signs each request with an ECDSA key and gives you the public key in the webhook settings. Hash the timestamp header plus the raw payload and check it against the signature header. The official helpers, such as @sendgrid/eventwebhook, wrap this.

    Watch for: frameworks that parse JSON before your code runs. Re-serialized JSON won't match the signature, so read the body as bytes.

  3. 3

    Treat every request as a batch

    SendGrid posts roughly every 30 seconds or when a batch reaches 768 KB, so one request can hold hundreds of events. Loop over the whole array.

  4. 4

    Drop duplicates by sg_event_id

    The same event can arrive twice. Keep the IDs you've processed and skip repeats, so one bounce isn't counted as two.

  5. 5

    Decide what each event type changes

    A bounce or drop marks the address undeliverable in the CRM, a spam report flags the account, an unsubscribe updates preferences, and clicks feed engagement data to whoever uses it. An event that only reaches a log changes nothing.

How SendGrid events go missing in production

The endpoint was down for a day

How you'll know: A gap in your event data that lines up with a deploy or an outage.

Fix: Retries stop 24 hours after each event, so a long outage loses events for good. Put a queue in front of the processing code so a broken deploy can't refuse requests, and alert when no events have arrived for an hour.

Only the test events ever worked

How you'll know: Test Your Integration passes, but real traffic fails verification or is ignored.

Fix: The test sends example events, not your mail. Check the handler against the real payload shape, including your custom arguments, and the signature on the raw request.

Parse posts arrive with no attachments

How you'll know: Inbound messages show up, but the files your process needs are missing.

Fix: Attachments come as separate form fields in multipart/form-data. Read them from the form parts, or switch to the raw MIME option and parse the message yourself.

Personal data in categories or custom arguments

How you'll know: Email addresses or names placed in categories or unique arguments to make matching easier.

Fix: SendGrid stores those fields as non-PII, and they generally can't be redacted later. Pass an internal ID instead and look the person up on your side.

Questions people ask

What events does the SendGrid Event Webhook send?

Processed, dropped, delivered, deferred and bounce for delivery; open and click for engagement; plus spam report, unsubscribe, and group unsubscribe and resubscribe for sends using subscription groups. You choose which ones under Actions to be posted.

Can SendGrid send more than one event in a webhook request?

Yes, usually. Events are batched and posted about every 30 seconds or when the batch reaches 768 KB, so the body is an array. Code that reads only the first item drops the rest without any error.

What is SendGrid Inbound Parse?

The feature for receiving email. You point a domain or subdomain's MX record at mx.sendgrid.net, and each message sent there is posted to your URL as form fields (sender, recipient, subject, body, attachments) instead of landing in a mailbox.

Should I verify the SendGrid webhook signature?

Yes, whenever an event changes anything, like suppressing an address or flagging an account. Without it, anyone who finds the URL can post a fake bounce. Turn on Signature Verification, keep the public key, and verify the raw body before parsing.

Does SendGrid retry a webhook if my endpoint is down?

For the Event Webhook, yes: any response other than 2xx is retried at increasing intervals for up to 24 hours after the event, and each new failing event gets its own 24 hours. Inbound Parse has its own retry rule, which SendGrid's support notes put at 72 hours.

Why does my SendGrid webhook receive duplicate events?

SendGrid says duplicates can happen, and slow responses that trigger retries make them more likely. Store each sg_event_id and skip any you've already handled.

Who can build and run a SendGrid webhook listener for us?

n-frames builds it: a signed, deduplicating endpoint that answers fast, then sends each bounce, complaint, unsubscribe or parsed reply to the CRM, help desk or database where it should change something. It also alerts you when an hour passes with no events.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.