Webhooks
Get a signed POST when a bulk list finishes, instead of polling.
Set up#
Add one https endpoint under Settings, then Webhooks. Use Send test event to check your receiver. The URL must be public: private, loopback and cloud-metadata addresses are refused, and redirects are not followed.
| Field | Type | Description |
|---|---|---|
| bulk_job.completed | event | A list finished. data.job is the same object as GET /v1/bulk/jobs/{id}. |
| bulk_job.failed | event | A list stopped with an error; unused credits were refunded. |
| webhook.test | event | Sent by the Send test event button. |
| monitor.blacklist_listed | event | A monitored domain or IP is now on a blocklist. data has target, status and the lists. |
| monitor.blacklist_cleared | event | A monitored target that was listed is clean again. |
| monitor.dmarc_changed | event | A monitored domain's DMARC, SPF or DKIM records changed. data has the new grade and open problems. |
Delivery body
{
"id": "evt_…",
"type": "bulk_job.completed",
"created_at": "2026-10-26T10:15:00.000Z",
"data": { "job": { "id": "job_…", "status": "completed", "total": 1200, "counts": { "valid": 1000, "invalid": 150 } } }
}Verify the signature#
Every delivery carries Veridock-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of t + "." + rawBody using your signing secret. Compute it over the raw body, compare in constant time, and reject timestamps older than a few minutes.
Node.js
import { createHmac, timingSafeEqual } from "node:crypto";
export function isValid(rawBody, header, secret) {
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
return v1?.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}Delivery and retries#
- Answer with any
2xxwithin 5 seconds. Otherwise we retry once after about 2 seconds. - The last result is shown in Settings. A missed delivery never affects the job: poll the job endpoint as a fallback.
- Use
veridock-delivery(also the bodyid) to ignore duplicates.
Related