Webhooks

Webhooks let Sendex push real-time event notifications to your server the moment something happens — an email is sent, a recipient opens a message, a contact unsubscribes, and more. No polling required.

How it works

When a subscribed event occurs, Sendex delivers an HTTP POST request to your endpoint URL within seconds. Each request includes:

• A Content-Type: application/json header
• An X-Sendex-Signature header for authenticity verification
• A JSON body with event, created_at, and data

Sendex retries failed deliveries up to 3 times with exponential backoff. Your endpoint should return a 2xx status within 10 seconds — any non-2xx response or timeout is treated as a failure and retried. The last 30 days of delivery logs are available in the dashboard.

Payload format

Every webhook POST has the same envelope structure:

POST https://your-server.com/webhook
Content-Type: application/json
X-Sendex-Signature: sha256=<hmac-sha256-hex>

{
  "event": "email.sent",
  "created_at": "2026-03-05T12:00:00.000Z",
  "data": {
    "id": "abc123",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Welcome aboard"
  }
}

Verifying signatures

Every request is signed with HMAC-SHA256 using your endpoint's secret. Always verify the signature before processing the payload to ensure the request genuinely came from Sendex.

Compute HMAC-SHA256(secret, rawBody) where rawBody is the raw request body string (before any JSON parsing). Compare the result, prefixed with sha256=, to the X-Sendex-Signature header using a timing-safe comparison to prevent timing attacks.

import crypto from "crypto";

function verifyWebhook(
  rawBody: string,
  secret: string,
  signatureHeader: string
): boolean {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  const sigBuf = Buffer.from(signatureHeader);
  const expBuf = Buffer.from(expected);

  // Length check prevents timingSafeEqual from throwing
  return (
    sigBuf.length === expBuf.length &&
    crypto.timingSafeEqual(sigBuf, expBuf)
  );
}

import hmac, hashlib

def verify_webhook(raw_body: bytes, secret: str, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Events

Events are grouped into three categories: Email, Broadcast, and Contact. You can subscribe to any combination per endpoint.

Email events

{
  "id": "69a40a5f923b47ca68278e38",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Welcome aboard",
  "created_at": "2026-03-05T12:00:00.000Z"
}

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Welcome aboard",
  "error": "Account sending paused"
}

{
  "email_id": "69a40a5f923b47ca68278e38",
  "message_id": "0100019cbe53da54-9e5928a3-...",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Hello there",
  "received_at": "2026-03-05T12:00:00.000Z"
}

{
  "message_id": "0100019cbe53da54-9e5928a3-...",
  "from": "[email protected]",
  "to": ["[email protected]"]
}

{
  "message_id": "0100019cbe53da54-9e5928a3-...",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "bounce_type": "Permanent",
  "bounce_sub_type": "General"
}

{
  "message_id": "0100019cbe53da54-9e5928a3-...",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "complaint_feedback_type": "abuse"
}

{
  "message_id": "0100019cbe53da54-9e5928a3-...",
  "from": "[email protected]",
  "to": ["[email protected]"]
}

{
  "message_id": "0100019cbe53da54-9e5928a3-...",
  "from": "[email protected]",
  "to": ["[email protected]"],
  "link": "https://example.com/your-original-url"
}

Broadcast events

{
  "id": "69a40a5f923b47ca68278e38",
  "stats": {
    "total": 1000,
    "sent": 987,
    "failed": 3,
    "skipped": 10
  }
}

Contact events

{
  "contact_id": "69a40a5f923b47ca68278e38",
  "email": "[email protected]",
  "audience_id": "69a40a5f923b47ca68278e39"
}

Open & click tracking

Sendex automatically handles delivery event tracking on your behalf — there is nothing to configure. The email.delivered, email.bounced, email.complained, email.opened, and email.clicked events all fire automatically as they happen.

You write the HTML — we inject the tracking

You do not need to add anything special to your emails. When you send an email with an html body, Sendex (via AWS SES) automatically:

• Injects an invisible 1×1 tracking pixel at the bottom of your HTML — when the recipient's email client loads it, email.opened fires.
• Rewrites every <a href> link in your HTML to route through a tracking URL — when the recipient clicks, email.clicked fires and they are immediately redirected to the original destination.

Your recipients never see the tracking infrastructure — the pixel is invisible and link rewrites are transparent. The only thing you need to do is pass an html field in your request. If you only pass text, there is no HTML to inject into and these events will never fire.

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Your weekly digest",
  "html": "<p>Hello! Check out <a href=\"https://example.com/news\">this week's news</a>.</p>",
  "text": "Hello! Check out this week's news: https://example.com/news"
}

Quick reference