Webhooks e-mail

Envelope Structure

All payloads share this top-level structure:

{
  "event_id": "evt_8f3k2j1h9g6d",
  "event_type": "delivered",
  "timestamp": "2026-04-19T14:32:01Z",
  "message_id": "msg_abc123xyz",
  "recipient": "user@example.com",
  "data": {
    // event-specific fields
  }
}

Delivered Event

Fired when a message is accepted by the recipient's mail server.

{
  "event_id": "evt_8f3k2j1h9g6d",
  "event_type": "delivered",
  "timestamp": "2026-04-19T14:32:01Z",
  "message_id": "msg_abc123xyz",
  "recipient": "user@example.com",
  "data": {
    "smtp_response": "250 OK",
    "server": "mail-sor-iad.example.com",
    "delivery_latency_ms": 312
  }
}

Bounce Event

Fired when a message is rejected by the recipient's mail server. Includes bounce type (hard/soft) and error code.

{
  "event_id": "evt_9h4k3l2m7n5p",
  "event_type": "bounce",
  "timestamp": "2026-04-19T14:30:45Z",
  "message_id": "msg_abc123xyz",
  "recipient": "invalid@example.com",
  "data": {
    "bounce_type": "hard",
    "bounce_category": "invalid_email",
    "smtp_code": 550,
    "smtp_message": "No such user",
    "was_automatic": true
  }
}

Complaint Event

Fired when a recipient marks your message as spam. Automatically suppressed for future sends.

{
  "event_id": "evt_1a2b3c4d5e6f",
  "event_type": "complaint",
  "timestamp": "2026-04-19T15:01:22Z",
  "message_id": "msg_abc123xyz",
  "recipient": "user@example.com",
  "data": {
    "complaint_type": "abuse",
    "feedback_type": "auth-failure",
    "user_agent": "Mozilla/5.0 (complaint reporter)"
  }
}

Open Event

Fired when a message is opened by the recipient (requires tracking pixel).

{
  "event_id": "evt_7g8h9i0j1k2l",
  "event_type": "open",
  "timestamp": "2026-04-19T14:45:10Z",
  "message_id": "msg_abc123xyz",
  "recipient": "user@example.com",
  "data": {
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "os": "Windows 10",
    "client": "Chrome 124.0"
  }
}

Click Event

Fired when a recipient clicks a tracked link in the message.

{
  "event_id": "evt_3m4n5o6p7q8r",
  "event_type": "click",
  "timestamp": "2026-04-19T14:47:33Z",
  "message_id": "msg_abc123xyz",
  "recipient": "user@example.com",
  "data": {
    "link_id": "lnk_abc123",
    "url": "https://yoursite.com/confirm?token=xyz",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4)",
    "os": "iOS 17.4"
  }
}

Retry Schedule

Failed deliveries (non-2xx, timeout, connection error) are retried at increasing intervals: attempt 1 immediately, attempt 2 after 30 seconds, attempt 3 after 5 minutes, attempt 4 after 30 minutes, attempt 5 after 2 hours, attempt 6 after 5 hours. After 6 failed attempts, the event is marked as permanently failed and no further retries occur.

Best Practices for Retry-Safe Handlers

Timeout Behavior

If your endpoint does not respond within 10 seconds, the delivery is marked as failed and enters the retry queue immediately.

HMAC Signature Verification

Each webhook request includes an X-Sendarix-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your endpoint's shared secret. Always verify this signature before processing the payload.

// Node.js signature verification example
const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express.js middleware
app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-sendarix-signature'];
  const timestamp = req.headers['x-sendarix-timestamp'];
  const secret = process.env.WEBHOOK_SECRET;
  
  // Check timestamp freshness (reject > 5 min old)
  if (Date.now() - parseInt(timestamp, 10) * 1000 > 300000) {
    return res.status(401).send('Timestamp expired');
  }
  
  // Verify signature
  const rawBody = req.rawBody; // must be raw buffer, not parsed JSON
  if (!verifySignature(rawBody, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event
  const event = JSON.parse(rawBody);
  res.status(200).send('OK');
});

Timestamp Validation

Requests also include an X-Sendarix-Timestamp header. Reject any request where the timestamp is older than 5 minutes to prevent replay attacks.

Security Best Practices

Why Duplicates Happen

Sendarix retries any delivery that returns non-2xx, times out, or fails DNS. If your endpoint returns 200 OK but the response is lost mid-network, Sendarix retries and delivers a second copy. Some load balancers also cause duplicate deliveries when retrying failed requests upstream.

Idempotency Pattern

The standard approach uses a deduplication table keyed on event_id. Before processing, check if the event_id has been processed. If yes, return 200 OK immediately. If no, process the event, mark it as processed, then return 200 OK.

Implementation Example

This example uses a simple in-memory store. In production, use Redis or your database for durability across restarts.

// Node.js idempotent webhook handler
const processedEvents = new Map(); // Replace with Redis/DB in production

app.post('/webhooks', (req, res) => {
  const event = req.body;
  const eventId = event.event_id;

  // Idempotency check - reject if already processed
  if (processedEvents.has(eventId)) {
    console.log(`Duplicate event received: ${eventId}`);
    return res.status(200).send('OK'); // Still return 200 to stop retries
  }

  // Process the event
  try {
    switch (event.event_type) {
      case 'delivered':
        updateNotificationStatus(event.message_id, 'delivered');
        break;
      case 'bounce':
        suppressRecipient(event.recipient);
        break;
      case 'complaint':
        suppressRecipient(event.recipient, 'complaint');
        break;
    }

    // Mark as processed before returning
    processedEvents.set(eventId, Date.now());
    return res.status(200).send('OK');
  } catch (err) {
    console.error('Processing error:', err);
    return res.status(500).send('Processing failed');
  }
});

// TTL cleanup - run periodically in production
setInterval(() => {
  const cutoff = Date.now() - 24 * 60 * 60 * 1000;
  for (const [id, timestamp] of processedEvents) {
    if (timestamp < cutoff) processedEvents.delete(id);
  }
}, 60 * 60 * 1000);

Best Practices