API reference

Webhooks

Subscribe to events so you don't have to poll. Payloads are signed with HMAC-SHA256 and retried with exponential backoff for up to 24 hours.

Events

  • verification.completed — async single verification finished
  • job.completed — bulk job finished, results ready
  • job.failed — bulk job aborted, see error
  • account.low_balance — credits dropped below threshold

Payload

{
  "id": "evt_01JAE...",
  "type": "verification.completed",
  "created": 1718900000,
  "data": {
    "id": "ver_01JABXZ7K2P0",
    "email": "alex@example.com",
    "status": "valid",
    "score": 96
  }
}

Verifying signatures

Compute HMAC-SHA256 of the raw request body using your endpoint secret, then compare against X-Purelist-Signature in constant time.

import crypto from "crypto";

const expected = crypto
  .createHmac("sha256", process.env.PURELIST_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).end();
}

Retries & idempotency

Failures (non-2xx or timeout) are retried for 24 hours with exponential backoff. Every event carries a unique id; store seen IDs to make handlers idempotent.