Webhooks

Email Delivery Events

Receive real-time notifications about email delivery status. Configure your webhook URL in the dashboard. All events are signed with HMAC-SHA256 for security.

POSThttps://your-server.com/webhook/email/delivery
!

Always verify the webhook signature. Generate your webhook secret in the dashboard and use it to verify incoming requests. Compute the HMAC over the raw request body, not over re-serialized JSON.

Quick start

A listener that verifies the signature and then handles the event. Reply with a 2xx status once the event is accepted.

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

function verifySignature(rawBody, signature) {
  if (!signature) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  // timingSafeEqual throws when the lengths differ
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw keeps the body as a Buffer, exactly as it was sent
app.post('/webhook/email/delivery', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature(req.body, req.headers['x-webhook-signature'])) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, emailId, data } = JSON.parse(req.body.toString('utf8'));

  console.log('[Email Delivery] ' + event + ' - ' + emailId);

  if (event === 'delivered') {
    console.log('   Recipient: ' + data.recipientEmail);
  } else if (event === 'bounced') {
    console.log('   Reason: ' + data.reason);
  }

  res.status(200).json({ received: true });
});

app.listen(3001, () => {
  console.log('Email delivery webhook listener on port 3001');
  console.log('   POST /webhook/email/delivery');
});

Headers

  • X-Webhook-Signaturestringrequired

    HMAC-SHA256 signature of the request body. Format: sha256=hex_digest

Testing with ngrok

Expose your local listener to the internet and register the generated URL as your webhook URL in the dashboard.

ngrok http 3001
# Your webhook URL:
# https://abc123.ngrok.io/webhook/email/delivery

Events

Every event is a JSON object with event, timestamp and a data object. Open an event for its full payload and fields.

Your endpoint failing too often? See List Webhooks to check its status, or Retry All Failed to requeue what was missed.