Webhooks

curl -X POST https://send.tsmart.ai/webhooks \
  -H "Authorization: Bearer $TSMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://hooks.acme.com/tsmart",
    "events": ["email.delivered", "email.bounced", "email.delivery_delayed", "email.failed"]
  }'

{
  "object": "webhook",
  "id": "5d2c8f3e-1a7b-4c9d-8e6f-0a1b2c3d4e5f",
  "signing_secret": "whsec_mR2u3H8XqVb1yZ0kL7cT9wN4pE6sA5dF1gJ3hK8lM2o="
}

const { data, error } = await tsmart.webhooks.create({
  endpoint: "https://hooks.acme.com/tsmart",
  events: ["email.delivered", "email.bounced", "email.delivery_delayed", "email.failed"],
});
// Store data.signing_secret with your endpoint's configuration.

hook = client.webhooks.create({
    "endpoint": "https://hooks.acme.com/tsmart",
    "events": ["email.delivered", "email.bounced", "email.delivery_delayed", "email.failed"],
})
print(hook["signing_secret"])

{
  "type": "email.sent",
  "created_at": "2026-10-12T09:41:05.402Z",
  "data": {
    "created_at": "2026-10-12T09:41:05.120Z",
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@acme.com>",
    "to": ["jane@example.com"],
    "subject": "Order 1042 confirmed",
    "tags": { "category": "order_confirmation" },
    "message_id": "<4ef9a417-02e9-4d39-ad75-9611e0fcc33c@acme.com>"
  }
}

{
  "type": "email.bounced",
  "created_at": "2026-10-12T09:41:08.999Z",
  "data": {
    "created_at": "2026-10-12T09:41:05.120Z",
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@acme.com>",
    "to": ["no-such-user@example.com"],
    "subject": "Order 1042 confirmed",
    "tags": { "category": "order_confirmation" },
    "message_id": "<4ef9a417-02e9-4d39-ad75-9611e0fcc33c@acme.com>",
    "bounce": {
      "type": "Permanent",
      "subType": "General",
      "message": "550 5.1.1 <no-such-user@example.com>: Recipient address rejected: User unknown"
    }
  }
}

"bounce": {
  "type": "Temporary",
  "subType": "General",
  "message": "451 4.7.1 Please try again later"
}

"open": {
  "ipAddress": "203.0.113.24",
  "timestamp": "2026-10-12T10:02:44.318Z",
  "userAgent": "ExampleMailApp/2.1"
}

"click": {
  "ipAddress": "203.0.113.24",
  "link": "https://acme.com/orders/1042",
  "timestamp": "2026-10-12T10:03:10.077Z",
  "userAgent": "ExampleMailApp/2.1"
}

"failed": {
  "reason": "The mail server did not accept the email"
}

"suppressed": {
  "message": "The recipient is on the suppression list",
  "type": "bounce"
}

{
  "type": "domain.updated",
  "created_at": "2026-10-12T09:35:40.512Z",
  "data": {
    "id": "b7c1e0a2-5d0f-4a51-9a64-0f3c2a7d9e11",
    "name": "acme.com",
    "status": "verified",
    "created_at": "2026-10-12T09:30:11.412Z"
  }
}

import { createServer } from "node:http";
import { verifyWebhook, WebhookVerificationError } from "@tsmart/sdk";

const secret = process.env.TSMART_WEBHOOK_SECRET; // whsec_…

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const payload = Buffer.concat(chunks); // the raw body, exactly as received
    let event;
    try {
      event = verifyWebhook({ payload, headers: req.headers, secret });
    } catch (err) {
      res.writeHead(err instanceof WebhookVerificationError ? 400 : 500).end();
      return;
    }
    // Skip events you have already handled: req.headers["webhook-id"] is unique per event.
    console.log(event.type, event.data.email_id ?? event.data.name);
    res.writeHead(200).end();
  });
}).listen(3000);

import os
from http.server import BaseHTTPRequestHandler, HTTPServer

from tsmart import WebhookVerificationError, verify_webhook

SECRET = os.environ["TSMART_WEBHOOK_SECRET"]  # whsec_...


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        payload = self.rfile.read(int(self.headers.get("Content-Length", 0)))  # raw body
        try:
            event = verify_webhook(payload=payload, headers=dict(self.headers), secret=SECRET)
        except WebhookVerificationError:
            self.send_response(400)
            self.end_headers()
            return
        # Skip events you have already handled: the webhook-id header is unique per event.
        print(event["type"], event["data"].get("email_id"))
        self.send_response(200)
        self.end_headers()


HTTPServer(("", 8000), Handler).serve_forever()

import { createHmac, timingSafeEqual } from "node:crypto";

/** payload: the raw body (Buffer or string); headers: lower-case header names. Returns the event or throws. */
export function verifyTsmartWebhook(payload, headers, secret, toleranceSeconds = 300) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];
  if (!id || !timestamp || !signature) throw new Error("Missing webhook headers");
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    throw new Error("Timestamp outside the tolerance");
  }

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.`).update(payload).digest();
  const valid = signature.split(" ").some((entry) => {
    const [version, value] = entry.split(",");
    if (version !== "v1" || !value) return false;
    const given = Buffer.from(value, "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
  if (!valid) throw new Error("Invalid signature");
  return JSON.parse(payload.toString("utf8"));
}

import base64
import hashlib
import hmac
import json
import time


def verify_tsmart_webhook(payload: bytes, headers, secret: str, tolerance: int = 300):
    """payload: the raw body; headers: a mapping with lower-case names. Returns the event or raises ValueError."""
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signature = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signature:
        raise ValueError("Missing webhook headers")
    if not (timestamp.isascii() and timestamp.isdigit()) or abs(time.time() - int(timestamp)) > tolerance:
        raise ValueError("Timestamp outside the tolerance")

    if secret.startswith("whsec_"):
        secret = secret[len("whsec_"):]
    key = base64.b64decode(secret)
    signed = msg_id.encode() + b"." + timestamp.encode() + b"." + payload
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for entry in signature.split(" "):
        version, _, value = entry.partition(",")
        if version == "v1" and hmac.compare_digest(value.encode(), expected.encode()):
            return json.loads(payload)
    raise ValueError("Invalid signature")

{
  "type": "email.sent",
  "created_at": "2026-10-12T09:50:00.000Z",
  "data": {
    "created_at": "2026-10-12T09:50:00.000Z",
    "email_id": "00000000-0000-4000-8000-000000000000",
    "from": "Example <hello@example.com>",
    "to": ["someone@example.com"],
    "subject": "Test event",
    "tags": { "test": "true" }
  }
}

curl "https://send.tsmart.ai/webhooks/5d2c8f3e-1a7b-4c9d-8e6f-0a1b2c3d4e5f/events?limit=10" \
  -H "Authorization: Bearer $TSMART_API_KEY"

curl -X POST https://send.tsmart.ai/webhooks/5d2c8f3e-1a7b-4c9d-8e6f-0a1b2c3d4e5f/events/msg_2b7xQd9LmK3vR8sT1wYz5aBc4eF/replay \
  -H "Authorization: Bearer $TSMART_API_KEY"

curl -X POST https://send.tsmart.ai/webhooks/5d2c8f3e-1a7b-4c9d-8e6f-0a1b2c3d4e5f/signing-secret/rotate \
  -H "Authorization: Bearer $TSMART_API_KEY"