Updated November 13, 2026
Webhooks
Get results pushed to your server instead of polling: for pending single checks and for finished bulk jobs.
Events
| Event | Sent when |
|---|---|
| verification.completed | A single verification that returned pending has finished. |
| bulk.completed | A bulk job has finished and its results are ready to download. |
| bulk.failed | A bulk job couldn't be processed, for example an unreadable file. |
Payload
POST to your webhook_url
POST https://example.com/hooks/mailvet
MailVet-Signature: t=1763026867,v1=5f2b0c…
{
"event": "verification.completed",
"data": {
"id": "vrf_01JD8X9MRC",
"email": "j.okafor@harbor-logistics.example",
"result": "undeliverable",
"reason": "catch_all_no_mailbox",
"credits_charged": 1
}
}Check the signature
Every webhook is signed with your account's webhook secret. Reject requests whose signature doesn't match or whose timestamp is more than five minutes old.
Node.js
import crypto from "node:crypto";
// raw = the request body exactly as received, header = MailVet-Signature
export function isFromMailVet(raw, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", secret).update(parts.t + "." + raw).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}Delivery and retries
- Respond with any 2xx status within 10 seconds to acknowledge.
- Failed deliveries are retried with backoff for up to 24 hours.
- Events can arrive more than once; use
data.idto de-duplicate.