Event webhooks for transactional emails

Overview

Every message sent through the Email API carries an invisible tracking pixel and a reference ID. When the recipient opens the email, or when the message bounces, we record the event against your organization and deliver an HTTP POST to every active webhook you've subscribed to that event.

These are outbound webhooks for transactional delivery events — distinct from Inbound Email webhooks, which forward email received at your domain. The two are configured separately and never interfere.

Event types

A webhook subscribes to one or more events. The value below is what we send in the payload's event field and the X-Sendtrim-Event header.

Create & manage webhooks

Manage webhooks from Settings → Webhooks in the dashboard, or via the API. All endpoints are under /api/v1/email-api/webhooks and require your JWT in the Authorization: Bearer <token> header. Organization scoping is automatic.

Create a webhook

POST /api/v1/email-api/webhooks
Authorization: Bearer <your-jwt>
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/sendtrim",
  "description": "Production bounce + open handler",
  "events": ["OPENED", "BOUNCED"],
  "isActive": true
}

• url — required. Max 1024 characters.
• events — array of the event names above. An empty/omitted array means the webhook receives nothing until you add events.
• description — optional free text.
• isActive — defaults to true.

Returns 201 Created with the webhook, including a generated signing secret (prefixed whsec_). Store it — you need it to verify signatures.

{
  "id": 7,
  "url": "https://your-app.com/webhooks/sendtrim",
  "description": "Production bounce + open handler",
  "isActive": true,
  "events": ["OPENED", "BOUNCED"],
  "secret": "whsec_3f9c…",
  "createdAt": "2026-06-15T10:14:02"
}

List, update, delete

GET    /api/v1/email-api/webhooks          # list your webhooks
PUT    /api/v1/email-api/webhooks/{id}     # update url/description/events/isActive
DELETE /api/v1/email-api/webhooks/{id}     # soft delete (204 No Content)
GET    /api/v1/email-api/webhooks/event-types  # enumerate available events

On PUT, only the fields you send are changed. Pause a webhook without deleting it by setting isActive: false.

What we send (request)

We send a single POST to exactly the URL you registered — no extra paths or query strings:

POST <your-url>
Content-Type: application/json
X-Sendtrim-Event: email.opened
X-Sendtrim-Signature: sha256=2b6c…   # present when the webhook has a secret

<JSON body — see "JSON payload reference">

JSON payload reference

All events share the same envelope. The event-specific details live under data. Example for an open:

{
  "event": "email.opened",
  "referenceId": "em_8x2Lq7…",
  "messageId": "<CAJh+abc@mail.sendtrim.com>",
  "sender": "noreply@yourdomain.com",
  "subject": "Your receipt",
  "recipients": ["jane@example.com"],
  "organizationId": 17,
  "timestamp": "2026-06-15T10:14:33.482",
  "data": {
    "opens": 3
  }
}

The data object

Everything that's specific to an event type lives here, so the top-level envelope stays the same across events.

email.opened

"data": {
  "opens": 3        // running total of opens for this message, including this one
}

This event fires on every open, not just the first. Use opens if you only care about the first one (act when it equals 1).

email.bounced

"data": {
  "bounceCheckedAt": "2026-06-15T10:09:50.114"   // when we recorded the bounce
}

Verifying the signature

When a webhook has a secret (every webhook gets one at creation), we sign each request. The X-Sendtrim-Signature header is sha256=<hex>, where <hex> is the lowercase hex HMAC-SHA256 of the raw request body keyed by your webhook's secret.

Node.js (Express)

import crypto from "crypto";

// Capture the raw body for this route.
app.post(
  "/webhooks/sendtrim",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.get("X-Sendtrim-Signature") || "";
    const expected =
      "sha256=" +
      crypto.createHmac("sha256", process.env.SENDTRIM_WEBHOOK_SECRET)
        .update(req.body) // Buffer of raw bytes
        .digest("hex");

    const ok =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
    if (!ok) return res.sendStatus(401);

    res.sendStatus(200); // ack first
    const evt = JSON.parse(req.body.toString("utf8"));
    queue.publish("sendtrim-event", evt); // process async
  }
);

Python (Flask)

import hmac, hashlib

@app.post("/webhooks/sendtrim")
def sendtrim():
    raw = request.get_data()  # raw bytes
    expected = "sha256=" + hmac.new(
        SECRET.encode(), raw, hashlib.sha256
    ).hexdigest()
    got = request.headers.get("X-Sendtrim-Signature", "")
    if not hmac.compare_digest(expected, got):
        return ("", 401)
    evt = request.get_json()
    enqueue(evt)            # process async
    return ("", 200)

Delivery contract

Code samples

Acting on the first open only

function handleEvent(evt) {
  if (evt.event === "email.opened" && evt.data.opens === 1) {
    // first time this message was opened
    markOpened(evt.referenceId, evt.recipients[0]);
  }
  if (evt.event === "email.bounced") {
    suppress(evt.recipients[0], evt.data.bounceCheckedAt);
  }
}

Python (FastAPI), signature-verified

@app.post("/webhooks/sendtrim")
async def sendtrim(req: Request, bg: BackgroundTasks):
    raw = await req.body()
    expected = "sha256=" + hmac.new(
        SECRET.encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, req.headers.get("X-Sendtrim-Signature", "")):
        raise HTTPException(status_code=401)
    evt = json.loads(raw)
    bg.add_task(process_event, evt)   # ack now, work later
    return {"ok": True}

Troubleshooting

FAQ

How is this different from inbound webhooks?

Event webhooks notify you about outbound messages you sent (opens, bounces). Inbound webhooks forward email received at your domain. See Inbound Emails & Webhooks.

Do open events fire more than once?

Yes. Every pixel load produces an email.opened event with an incremented opens count. Use opens === 1 for “first open”.

Are payloads signed?

Yes — HMAC-SHA256 in X-Sendtrim-Signature using the secret generated when you created the webhook. Always verify it.

Will failed deliveries be retried?

Not today — each event is delivered once per active webhook. Retries are on our roadmap.

Why didn't opens register?

Open tracking relies on a pixel. Recipients with images disabled, or text-only clients, won't register an open — this is inherent to all email open tracking.