Skip to content
MailVet
Updated November 13, 2026

Webhooks

Get results pushed to your server instead of polling: for pending single checks and for finished bulk jobs.

Events

EventSent when
verification.completedA single verification that returned pending has finished.
bulk.completedA bulk job has finished and its results are ready to download.
bulk.failedA 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.id to de-duplicate.