Webhooks
Zevuki sends a POST request to your server when something happens to an email, so you don't have to poll. Add endpoints on the Webhooks page in the dashboard or with the API.
Events
| Event | When |
|---|---|
email.sent | Amazon SES accepted the email for delivery. |
email.delivered | The recipient's server accepted it. |
email.delivery_delayed | The recipient's server asked to try later. |
email.bounced | It bounced. data.bounce.type is Permanent (the address is now blocked) or Transient. |
email.complained | The recipient marked it as spam. The address is now blocked. |
email.failed | It couldn't be sent, for example a scheduled email whose recipient was blocked meanwhile. |
email.opened | The email was opened, for emails sent with track.opens. Approximate. |
email.clicked | A link in the email was clicked, for emails sent with track.clicks. data.click.link is the original address. |
email.received | New mail arrived in one of your mailboxes. |
Events about one email come once per recipient, with that address in data.recipient, and carry the email's tags.
{
"type": "email.bounced",
"created_at": "2026-11-14T10:02:31Z",
"data": {
"email_id": "em_5Gk2...",
"from": "Acme <hello@acme.dev>",
"to": ["old@example.com"],
"subject": "Welcome to Acme",
"created_at": "2026-11-14T10:02:11Z",
"recipient": "old@example.com",
"tags": { "user_id": "8812" },
"bounce": { "type": "Permanent", "message": "Permanent General: smtp; 550 5.1.1 user unknown" }
}
}Incoming mail
email.received includes the message's text and HTML (each up to 1 MB) and a list of its attachments. folder is Junk when the spam filter caught it, authenticated says whether the sender's domain was verified (DMARC), and automated marks out-of-office and list mail, which you shouldn't auto-reply to.
{
"type": "email.received",
"created_at": "2026-11-14T11:20:05Z",
"data": {
"mailbox_id": "17",
"mailbox": "support@shop.example",
"from": "Maya Chen <maya@example.com>",
"to": ["support@shop.example"],
"cc": [],
"subject": "Where is my order?",
"message_id": "<m1@example.com>",
"in_reply_to": "",
"text": "Hi, my order 4821 hasn't arrived.",
"html": "",
"attachments": [{ "filename": "receipt.pdf", "content_type": "application/pdf", "size": 48213 }],
"folder": "Inbox",
"authenticated": true,
"automated": false
}
}Verifying requests
Every request is signed with your endpoint's secret (it starts with whsec_) in the Standard Webhooks format, the same one Svix and Resend use. Their libraries verify it as is. Headers:
webhook-id: unique per event. Use it to ignore duplicates.webhook-timestamp: Unix seconds. Reject requests older than 5 minutes.webhook-signature:v1,and the base64 HMAC-SHA256 ofid.timestamp.body, keyed with the base64-decoded part of the secret afterwhsec_.
The same three headers are also sent with a svix- prefix.
import { Webhook } from "svix" // or "standardwebhooks"
const wh = new Webhook(process.env.ZEVUKI_WEBHOOK_SECRET) // "whsec_..."
app.post("/webhooks/zevuki", express.raw({ type: "application/json" }), (req, res) => {
let event
try {
event = wh.verify(req.body, req.headers) // Throws if the signature is wrong.
} catch {
return res.status(400).end()
}
if (event.type === "email.bounced") markBounced(event.data.recipient)
res.status(200).end()
})Retries
Answer with any 2xx status within 15 seconds. Otherwise Zevuki retries after 5 seconds, 30 seconds, 2 minutes, 10 minutes, 30 minutes, then 1, 3, 6 and 12 hours, about a day in total, then marks the delivery failed. Redirects aren't followed. On the Webhooks page you can see each delivery, its response, and send it again.
Managing webhooks with the API
| Request | What it does |
|---|---|
POST /v1/webhooks | Add: {"endpoint": "https://…", "events": ["email.delivered", "email.bounced"]}. Returns the signing_secret. |
GET /v1/webhooks | List. |
GET /v1/webhooks/{id} | One webhook. |
PATCH /v1/webhooks/{id} | Change endpoint, events or enabled. |
DELETE /v1/webhooks/{id} | Remove. |
Endpoints must be public https:// URLs. An account can have up to 10.