@turbosmtp/webhook

Parse and authenticate TurboSMTP event webhooks.

npm install @turbosmtp/webhook

Requires Node.js 22+.

Usage

TurboSMTP does not sign its webhooks. Instead, set HTTP Basic credentials on the webhook URL in the dashboard (https://user:[email protected]/webhook); they arrive as an Authorization: Basic header. Verify them against the same user:pass secret, then parse the body.

import { parseWebhookEvents, verifyBasicAuth } from "@turbosmtp/webhook";

// Example with a Node http handler; any framework works.
function handle(req, res, rawBody) {
  if (!verifyBasicAuth(req.headers.authorization, process.env.TURBOSMTP_WEBHOOK_SECRET!)) {
    res.writeHead(403).end();
    return;
  }

  for (const event of parseWebhookEvents(rawBody)) {
    // event: { mid, email, status, timestamp: Date, url?, ip?, userAgent?, referenceId?, raw }
    console.log(event.status, event.email, event.timestamp);
  }

  res.writeHead(204).end();
}

parseWebhookEvents() accepts the body as a parsed object, an array, or a JSON string, and returns typed events. Statuses are delivered upper-cased (DELIVERED, BOUNCED, OPENED, CLICKED, ...); mid is kept as a string. It throws if the body is not valid JSON or an event is missing required fields.