Set up an endpoint
- 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. - Copy the endpoint's signing secret. It starts with
whsec_and each endpoint has its own. - You can have up to 5 endpoints per account in total. Test endpoints only receive test checks, and live endpoints only receive live checks.
Events
| Event type | When it is sent | Verification status | Charged (live) |
|---|---|---|---|
verification.created | A verification was created (API, SDK, widget or dashboard). | pending | No |
verification.started | The customer opened the check and started it. | in_progress | No |
verification.review | The check needs a manual review. A final result follows. | in_review | Not yet: charged once, when it ends approved or declined |
verification.completed | The check finished and was approved. | completed, result approved | Yes (live) |
verification.failed | The check finished and was declined. | completed, result declined | Yes (live) |
verification.expired | The link expired or the customer abandoned the check. | expired or abandoned | No |
verification.canceled | You cancelled the check before it finished. | canceled | No |
verification.reviewis not final. Averification.completedorverification.failedfollows once the review is decided.verification.expiredcovers both a link that ran out (statusexpired, links last 7 days) and a customer who abandoned the check (statusabandoned). Readdata.object.statusto 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.
| Field | Type | Meaning |
|---|---|---|
id | string | Unique event id, starting evt_. Use it to de-duplicate. |
object | string | Always "event". |
type | string | One of the event types above. |
created | integer | When the event was created, Unix seconds. |
livemode | boolean | false for test checks. |
data.object | object | The verification. See the verification object. |
{
"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:
AIS-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>- Read the raw request body exactly as received. Parsing and re-serialising the JSON changes it and breaks the signature.
- Split the header on commas and take
tandv1. - Compute HMAC-SHA256 of the string
<t>.<raw body>using the full endpoint secret (includingwhsec_) as the key, and hex-encode it. - Compare it with
v1using a constant-time comparison. - Reject the request if
tis 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
idand 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
| Tool | What it does |
|---|---|
| Send test event | Sends 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 log | Every attempt for each endpoint: event, status code, error and timing. |
| Resend | Sends a logged delivery again now, with the same event id and body and a fresh signature. |
| Rotate secret | Issues a new whsec_ secret for the endpoint. Update your server straight away. |
| Disable | Stops deliveries to the endpoint without deleting it. |