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
| Event | When |
|---|---|
email.sent | Accepted by Voozin and handed to the queue |
email.scheduled, email.canceled | A scheduled email was created or canceled |
email.delivered | The receiving server accepted the message |
email.delivery_delayed | A temporary failure; Voozin keeps retrying |
email.bounced | A permanent failure. The address is suppressed |
email.complained | The recipient marked the message as spam |
email.opened, email.clicked | Tracking events, when tracking is on |
email.unsubscribed | The recipient used the unsubscribe link |
contact.created, contact.updated, contact.unsubscribed | Marketing contact changes |
inbound.received | Mail 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-separatedv1,<base64>signatures, an HMAC-SHA256 of{webhook-id}.{webhook-timestamp}.{raw body}keyed with the base64-decoded part of the secret afterwhsec_.
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 wrongWithout 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.