Webhooks

When an event occurs we POST a JSON body to your endpoint. Every payload has the same envelope — event, data, transaction_id and timestamp — with the fields inside data varying by event.

Delivery events (email.delivered, email.bounced)

{
  "event": "email.delivered",
  "data": {
    "transaction_id": "email_mjgc0ejr_3ca715bfb7a0",
    "type": "email",
    "status": "delivered",
    "email_id": "msg_8f21c0d4a97b",
    "to": ["recipient@example.com"],
    "subject": "Welcome to our platform!",
    "detail": "",
    "timestamp": "2026-08-23T10:30:04.512000+00:00"
  },
  "transaction_id": "email_mjgc0ejr_3ca715bfb7a0",
  "timestamp": "2026-08-23T10:30:04.702000+00:00"
}

Send events (email.sent, email.failed)

{
  "event": "email.sent",
  "data": {
    "transaction_id": "email_mjgc0ejr_3ca715bfb7a0",
    "type": "email",
    "status": "sent",
    "to": ["recipient@example.com"],
    "subject": "Welcome to our platform!",
    "email_id": "msg_8f21c0d4a97b",
    "from": "Your App <hello@yourdomain.com>",
    "cost": 0.01,
    "error": null
  },
  "transaction_id": "email_mjgc0ejr_3ca715bfb7a0",
  "timestamp": "2026-08-23T10:30:00.318000+00:00"
}

• transaction_id appears both in the envelope and inside data, and matches the value returned by the send endpoint.
• email_id is the per-message id, so it also matches an entry in a batch results[].
• On email.bounced, data.status is "failed" and data.detail carries the reason reported by the receiving server. Always branch on event, not on data.status.
• Treat data as open-ended — we add fields over time, so ignore anything you don't recognise.

When you register a webhook, you'll receive this response. Save the secret - it's only shown once!

{
  "success": true,
  "data": {
    "id": "e406c83c-50bc-4783-b5fc-4beafe6bf5eb",
    "url": "https://your-server.com/webhooks/email",
    "events": [
      "email.sent",
      "email.delivered",
      "email.bounced",
      "email.complained",
      "email.opened",
      "email.clicked",
      "email.delivery_delayed",
      "email.failed"
    ],
    "secret": "whsec_21be983f359112f9e07658ed2bddcee3...",
    "active": true,
    "created_at": "2026-08-23T23:25:12.006000+00:00"
  }
}

Every request is signed with your webhook secret. The signature is sha256= followed by the hex-encoded HMAC-SHA256 of the raw request body, sent in the X-SendComms-Signature header. Compute it over the bytes you received — re-serialising the parsed JSON will not reproduce the same digest.

// Node.js / Express — note express.raw(), not express.json()
const crypto = require('crypto');

app.post('/webhooks/sendcomms',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const secret = process.env.SENDCOMMS_WEBHOOK_SECRET; // whsec_...
    const received = req.headers['x-sendcomms-signature'] || '';

    const expected = 'sha256=' +
      crypto.createHmac('sha256', secret)
        .update(req.body)          // the raw Buffer, unmodified
        .digest('hex');

    const a = Buffer.from(received);
    const b = Buffer.from(expected);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const { event, data, transaction_id } = JSON.parse(req.body.toString());
    console.log(`${event} for ${transaction_id}`);

    // Acknowledge first, process asynchronously
    res.status(200).json({ received: true });
  }
);

# Python / Flask
import hmac, hashlib, os
from flask import request, jsonify

@app.post('/webhooks/sendcomms')
def sendcomms_webhook():
    secret = os.environ['SENDCOMMS_WEBHOOK_SECRET'].encode()
    raw = request.get_data()                       # raw bytes, unmodified
    expected = 'sha256=' + hmac.new(secret, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, request.headers.get('X-SendComms-Signature', '')):
        return jsonify(error='Invalid signature'), 401

    payload = request.get_json()
    print(payload['event'], payload['transaction_id'])
    return jsonify(received=True), 200