Webhooks

Setting one up

Create endpoints under Account → Webhooks. Delivery is handled by Svix, so failed deliveries are retried on an exponential backoff rather than dropped.

The event you will receive

A completed verification sends verification.decision:

{
  "type": "verification.decision",
  "id": "a354461f-b116-4290-8969-8506255dc2fa",
  "result": "positive",
  "adverse_media_results": {},
  "sanctions_results": {},
  "result_info": {
    "status": "success",
    "verification": {
      "id": "fa9ddce9-45c9-4e8d-a097-d612d08752db",
      "status": "approved",
      "code": 9001,
      "acceptanceTime": "2023-10-18T04:38:59.680166Z",
      "decisionTime": "2023-10-18T04:46:37.594669Z",
      "document": {
        "type": "DRIVERS_LICENSE",
        "country": "AU"
      },
      "person": { }
    },
    "technicalData": { "ip": "124.187.226.22" }
  }
}

result is the headline outcome. result_info.verification.status carries the detail, and adverse_media_results and sanctions_results are populated when screening ran.

Verify every payload

An unverified webhook is an open endpoint that anyone can post to. Each webhook has its own signing secret, shown alongside the endpoint. Verify the signature before acting on the contents.

const crypto = require('crypto');

const signedContent = `${svix_id}.${svix_timestamp}.${body}`;
const secret = process.env.STACKGO_WEBHOOK_SECRET;  // "whsec_..."

// the secret is base64 after the prefix
const secretBytes = Buffer.from(secret.split('_')[1], 'base64');

const signature = crypto
  .createHmac('sha256', secretBytes)
  .update(signedContent)
  .digest('base64');

// compare against the svix-signature header before trusting the body

Svix documents the full procedure, including timestamp tolerance and key rotation, in verifying payloads manually.

Two things worth doing

• Respond fast, process later. Acknowledge with a 2xx and queue the work. Slow handlers look like failures and get retried.
• Expect duplicates. Retries mean the same event can arrive twice. Key your processing on the verification id.