Webhooks · Signed with HMAC-SHA256

Webhooks: know the moment a check changes

We POST a signed event to your HTTPS endpoint when a verification is created, started, sent to review, approved, declined, expired or cancelled.

Set up an endpoint

  1. Open Webhooks in the dashboard and add an endpoint: a public https:// URL, its mode (test or live) and the events you want. Leave the event list empty to receive every event.
  2. Copy the endpoint's signing secret. It starts with whsec_ and each endpoint has its own.
  3. You can have up to 5 endpoints per account in total. Test endpoints only receive test checks, and live endpoints only receive live checks.
Local URLs (localhost, private IP ranges) are not accepted. To test a receiver on your own machine, expose it through a tunnelling tool that gives you a public https URL.

Events

Event typeWhen it is sentVerification statusCharged (live)
verification.createdA verification was created (API, SDK, widget or dashboard).pendingNo
verification.startedThe customer opened the check and started it.in_progressNo
verification.reviewThe check needs a manual review. A final result follows.in_reviewNot yet: charged once, when it ends approved or declined
verification.completedThe check finished and was approved.completed, result approvedYes (live)
verification.failedThe check finished and was declined.completed, result declinedYes (live)
verification.expiredThe link expired or the customer abandoned the check.expired or abandonedNo
verification.canceledYou cancelled the check before it finished.canceledNo
  • verification.review is not final. A verification.completed or verification.failed follows once the review is decided.
  • verification.expired covers both a link that ran out (status expired, links last 7 days) and a customer who abandoned the check (status abandoned). Read data.object.status to tell them apart.

Event envelope

Every event has the same envelope. data.object is the verification, in exactly the shape GET /api/v1/verifications/{id} returns, as it was when the event was sent.

FieldTypeMeaning
idstringUnique event id, starting evt_. Use it to de-duplicate.
objectstringAlways "event".
typestringOne of the event types above.
createdintegerWhen the event was created, Unix seconds.
livemodebooleanfalse for test checks.
data.objectobjectThe verification. See the verification object.
POST to your endpoint (example values)
{
  "id": "evt_5c1e9a7b3f2d4e6a8b0c1d2e",
  "object": "event",
  "type": "verification.completed",
  "created": 1763540240,
  "livemode": false,
  "data": {
    "object": {
      "id": "cmi4x0abc0001xyz",
      "object": "verification",
      "livemode": false,
      "status": "completed",
      "result": "approved",
      "reference": "order_1234",
      "metadata": {
        "plan": "gold"
      },
      "customer": {
        "email": "jane@example.com",
        "name": "Jane Citizen",
        "phone": null
      },
      "document": {
        "type": "driving_licence",
        "country": "Australia",
        "country_code": "AUS"
      },
      "checks": {
        "document": {
          "status": "passed"
        },
        "face_match": {
          "status": "passed",
          "score": 96.8
        },
        "liveness": {
          "status": "passed"
        },
        "aml": {
          "status": "passed",
          "hits": 0
        }
      },
      "verification_url": "https://portal.australianidentitysolutions.com.au/v/cmi4x0abc0001xyz",
      "redirect_url": null,
      "report_url": "https://portal.australianidentitysolutions.com.au/api/v1/verifications/cmi4x0abc0001xyz/report.pdf",
      "source": "api",
      "created_at": 1763540000,
      "started_at": 1763540060,
      "completed_at": 1763540240,
      "expires_at": 1764144800
    }
  }
}

Verify the signature

Each request carries this header:

Header format
AIS-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>
  1. Read the raw request body exactly as received. Parsing and re-serialising the JSON changes it and breaks the signature.
  2. Split the header on commas and take t and v1.
  3. Compute HMAC-SHA256 of the string <t>.<raw body> using the full endpoint secret (including whsec_) as the key, and hex-encode it.
  4. Compare it with v1 using a constant-time comparison.
  5. Reject the request if t is more than 5 minutes from your server's clock (replay protection).

Older integrations can still check X-AIS-Signature (a hex HMAC-SHA256 of the raw body alone) and X-AIS-Timestamp (milliseconds), which are still sent. New code should use AIS-Signature, because it binds the timestamp to the signature.

Signature code in six languages

Copy-ready receivers. Each one rejects a bad or stale signature with 400 and replies 200 to a good one.

webhook.mjs (Express)

// Node + Express. Use the RAW body: re-serialised JSON will not match the signature.
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.AIS_WEBHOOK_SECRET; // the full secret, including "whsec_"

function verify(rawBody, header) {
  const parts = Object.fromEntries(
    String(header || "").split(",").map((p) => p.split("=", 2))
  );
  const t = Number(parts.t);
  if (!t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // 5-minute tolerance
  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest("hex");
  return parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

app.post("/webhooks/ais", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify(raw, req.get("AIS-Signature"))) return res.status(400).send("bad signature");

  const event = JSON.parse(raw);
  res.sendStatus(200); // reply fast, then do the work

  if (await alreadyProcessed(event.id)) return; // de-duplicate on the event id
  const v = event.data.object; // same shape as GET /api/v1/verifications/{id}
  if (event.type === "verification.completed") { /* approved: v.reference, v.checks ... */ }
  if (event.type === "verification.failed")    { /* declined */ }
});

app.listen(3000);

Retries and timeouts

  • The first attempt is sent straight away. Your endpoint must reply with a 2xx status within 10 seconds.
  • Any other status, a timeout or a connection error is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, 24 hours (seven attempts in all). Redirects are not followed, so give us the final URL.
  • A retry is the same event with the same id and body, and a fresh signature and timestamp.
  • If an endpoint is disabled, its pending deliveries stop.

Best practice

Respond 2xx fast

Verify the signature, store the event, reply 200, then do the slow work (CRM updates, emails, PDF download) in a background job. Slow handlers time out and get retried.

Handle events idempotently

The same event can arrive more than once (a retry after your reply was lost, or a manual resend). Record each event.id you have processed and skip repeats.

Don't rely on order

Events can arrive out of order after retries. Use data.object.status, or call GET /api/v1/verifications/{id} for the latest state, rather than assuming the sequence.

Check the mode

Use livemode to make sure a test event never unlocks a real account.

Keep secrets secret

Store whsec_ secrets in environment variables. If one leaks, rotate it in the dashboard (the old secret stops working).

Dashboard tools

ToolWhat it does
Send test eventSends one signed sample event of the type you choose to the endpoint. One attempt, no retries, and free. The sample verification id is ver_test_sample.
Delivery logEvery attempt for each endpoint: event, status code, error and timing.
ResendSends a logged delivery again now, with the same event id and body and a fresh signature.
Rotate secretIssues a new whsec_ secret for the endpoint. Update your server straight away.
DisableStops deliveries to the endpoint without deleting it.