How to Test SendGrid Webhooks

What SendGrid Sends

SendGrid's Event Webhook fires a single HTTP POST for every tracked email event. Unlike most webhook providers that send one event per request, SendGrid batches multiple events into one POST as a JSON array. You may receive dozens of event objects in a single request during high-volume sends.

Step 1 — Generate a Requex Endpoint

Open requex.me in your browser. A unique webhook URL is generated automatically — no account required. It looks like:

https://requex.me/hook/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Copy this URL. You will paste it into SendGrid's Event Webhook settings in the next step. Keep the Requex tab open so you can watch requests arrive in real time.

Step 2 — Configure SendGrid Event Webhook

1. Log in to app.sendgrid.com and go to Settings → Mail Settings → Event Webhooks.
2. Click Create new webhook (or edit the existing one).
3. Paste your Requex URL into the HTTP Post URL field.
4. Toggle on the event types you want to capture: Delivered, Opens, Clicks, Bounces, Spam Reports, and Unsubscribes are the most useful for testing.
5. Optionally enable Signed Event Webhook to test signature verification (see below).
6. Click Save. SendGrid immediately sends a test POST to verify the URL is reachable — Requex accepts it and responds 200.

Step 3 — Trigger a Test Event

The fastest way to generate real events without sending to live recipients is to use SendGrid's built-in test button. In the Event Webhook settings, click Test Your Integration. SendGrid will POST a synthetic batch of events to your Requex URL covering all enabled event types.

For a more realistic test, send an actual transactional email to an address you control (such as a Gmail account with click and open tracking enabled), then open the email and click a link. Each action generates a separate event that accumulates in the batch.

Step 4 — Inspect the Payload

Switch back to your Requex tab. You should see a new POST request. Click it to expand the full payload. SendGrid always sends a JSON array — even if there is only one event.

[
  {
    "email": "user@example.com",
    "event": "open",
    "timestamp": 1712345678,
    "sg_message_id": "abc123.filter0001p3las1-12345-67ABCDE0-1.0",
    "useragent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
    "ip": "192.0.2.1",
    "sg_event_id": "sendgrid_internal_event_id_1"
  },
  {
    "email": "user@example.com",
    "event": "click",
    "timestamp": 1712345690,
    "url": "https://yoursite.com/promo",
    "sg_message_id": "abc123.filter0001p3las1-12345-67ABCDE0-1.0",
    "useragent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
  }
]

Notice the key fields: event is the event type, email is the recipient, timestamp is Unix epoch, and sg_message_id lets you correlate events back to the original send. Check the Headers tab in Requex to see the signature header if you enabled Signed Event Webhooks.

Signed Event Webhooks and Signature Verification

When Signed Event Webhooks are enabled, SendGrid adds an X-Twilio-Email-Event-Webhook-Signature header and an X-Twilio-Email-Event-Webhook-Timestamp header to every request. The signature is an ECDSA signature (P-256 curve) over the concatenated timestamp and raw request body.

Use Requex to capture the exact raw body and headers, then test your verification logic locally before deploying:

// Node.js — verify SendGrid ECDSA signature
const crypto = require('crypto');

function verifySendGridSignature(publicKey, payload, signature, timestamp) {
  const timestampedPayload = timestamp + payload;
  const verify = crypto.createVerify('SHA256');
  verify.update(timestampedPayload);
  return verify.verify(
    { key: publicKey, format: 'der', type: 'spki', encoding: 'base64' },
    signature,
    'base64'
  );
}

// Express handler
app.post('/webhooks/sendgrid',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-twilio-email-event-webhook-signature'];
    const ts  = req.headers['x-twilio-email-event-webhook-timestamp'];
    const key = process.env.SENDGRID_WEBHOOK_PUBLIC_KEY;

    if (!verifySendGridSignature(key, req.body.toString(), sig, ts)) {
      return res.status(403).send('Invalid signature');
    }

    const events = JSON.parse(req.body);
    events.forEach(evt => console.log(evt.event, evt.email));
    res.sendStatus(200);
  }
);

You can retrieve the public key from SendGrid Mail Settings → Event Webhooks → Verification Key. Use Requex to capture a real signed payload, copy the body and headers, and test the verification function offline before pointing to your production server.

Common Issues