Events and inboundView as Markdown

Webhooks

Webhooks push events to your server as they happen: deliveries, bounces, opens, clicks, unsubscribes and inbound mail. Every request is signed with the Standard Webhooks scheme so you can prove it came from Voozin.

Add an endpoint

In the dashboard open Developers → Webhooks → Add endpoint, or call the API with a key that has the webhooks scope:

curl https://api.voozin.com/v1/webhooks \
  -H "Authorization: Bearer $VOOZIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://acme.com/api/webhooks/voozin", "events": ["email.delivered", "email.bounced", "inbound.received"] }'

The response includes the signing secret (whsec_…). Store it as VOOZIN_WEBHOOK_SECRET. An empty events list subscribes to every event type, including future ones.

Endpoints must be public https URLs. Private and loopback addresses are refused.

Event types

EventWhen
email.sentAccepted by Voozin and handed to the queue
email.scheduled, email.canceledA scheduled email was created or canceled
email.deliveredThe receiving server accepted the message
email.delivery_delayedA temporary failure; Voozin keeps retrying
email.bouncedA permanent failure. The address is suppressed
email.complainedThe recipient marked the message as spam
email.opened, email.clickedTracking events, when tracking is on
email.unsubscribedThe recipient used the unsubscribe link
contact.created, contact.updated, contact.unsubscribedMarketing contact changes
inbound.receivedMail arrived for an inbound route

Payload

Each delivery is a POST with a JSON body:

{
  "type": "email.delivered",
  "timestamp": "2026-10-26T10:04:12.511Z",
  "data": {
    "email_id": "6f1c0e7a-2d4b-4c1e-9a51-0b7f3c2e8d10",
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com"],
    "recipient": "ada@example.com",
    "subject": "Your receipt for order #1042",
    "tags": { "category": "receipt" },
    "metadata": { "order_id": 1042 },
    "campaign_id": null,
    "contact_id": null,
    "created_at": "2026-10-26T10:04:10+00:00"
  }
}

Email events are sent per recipient (recipient) and include the tags and metadata you sent, so you can link an event to your own records. Some events add details, such as the bounce reason. Message-level events (email.sent, email.scheduled, email.canceled) have no recipient. Email events cover mail sent through the API and campaigns; mail sent from mailboxes (webmail, SMTP) does not produce webhooks.

Verify the signature

Each request carries three headers:

  • webhook-id: the message id. It stays the same across retries, so use it to ignore duplicates.
  • webhook-timestamp: Unix seconds. Reject requests older than five minutes.
  • webhook-signature: one or more space-separated v1,<base64> signatures, an HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body} keyed with the base64-decoded part of the secret after whsec_.

Always verify against the raw request body, before parsing JSON.

With the Node.js SDK:

import { verifyWebhook } from "voozin";
 
const event = await verifyWebhook(rawBody, request.headers, process.env.VOOZIN_WEBHOOK_SECRET!);
// throws WebhookVerificationError when the signature or timestamp is wrong

Without the SDK, in Node.js:

import crypto from "node:crypto";
 
export function verifyWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
  return headers["webhook-signature"].split(" ").some((sig) => {
    const [, value] = sig.split(",");
    return value && value.length === expected.length && crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected));
  });
}

In Python:

import base64, hashlib, hmac, time
 
def verify_webhook(secret: str, headers: dict, raw_body: bytes) -> bool:
    msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.".encode() + raw_body, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(sig.split(",", 1)[-1], expected) for sig in headers["webhook-signature"].split())

In PHP:

function voozin_verify_webhook(string $secret, array $headers, string $rawBody): bool {
    $id = $headers['webhook-id'] ?? '';
    $ts = $headers['webhook-timestamp'] ?? '';
    if (abs(time() - (int) $ts) > 300) return false;
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "$id.$ts.$rawBody", $key, true));
    foreach (explode(' ', $headers['webhook-signature'] ?? '') as $sig) {
        $parts = explode(',', $sig, 2);
        if (isset($parts[1]) && hash_equals($expected, $parts[1])) return true;
    }
    return false;
}

The official Standard Webhooks libraries work too.

Retries

Any 2xx response within 10 seconds counts as delivered. Respond quickly and do slow work in a background job.

Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 1 hour, 3 hours, 6 hours and 12 hours. An endpoint that keeps failing for 5 days is disabled and the organization's admins are emailed; enabling it again clears the failure state.

Logs and replays

The dashboard shows every delivery with the request, the response and the timing. You can replay one delivery, or every failed delivery in a time range after an outage. Over the API: GET /v1/webhooks/:id/deliveries, POST /v1/webhooks/:id/deliveries/:deliveryId/replay and POST /v1/webhooks/:id/replay.

POST /v1/webhooks/:id/test sends a test event. POST /v1/webhooks/:id/secret/rotate issues a new secret.