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.

FieldTypeDescription
bulk_job.completedeventA list finished. data.job is the same object as GET /v1/bulk/jobs/{id}.
bulk_job.failedeventA list stopped with an error; unused credits were refunded.
webhook.testeventSent by the Send test event button.
monitor.blacklist_listedeventA monitored domain or IP is now on a blocklist. data has target, status and the lists.
monitor.blacklist_clearedeventA monitored target that was listed is clean again.
monitor.dmarc_changedeventA 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 2xx within 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 body id) to ignore duplicates.

Related