# 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](https://www.standardwebhooks.com/) 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:

```bash
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](https://voozin.com/docs/inbound) |

## Payload

Each delivery is a `POST` with a JSON body:

```json
{
  "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:

```ts
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:

```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:

```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:

```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](https://github.com/standard-webhooks/standard-webhooks) 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.
