Docs / Webhooks

Reliable webhook processing

Treat webhook delivery as at-least-once. Verify signatures, dedupe events, and keep replay-safe handlers.

Webhook lifecycle

sequenceDiagram
  participant AppClient as User Browser (your app)
  participant AppServer as Your Server
  participant AV as Age Verify API
  participant WH as Your Webhook

  AppServer->>AV: Create session (server-side)
  AV-->>AppServer: sessionId + client token (short-lived)
  AppServer-->>AppClient: Return client token
  AppClient->>AV: Run in-browser check (encrypted signals)
  AV-->>AppClient: Local status + submit receipt
  AppServer->>AV: Finalize session (server-side)
  AV-->>AppServer: Signed outcome (pass/fail + metadata)
  AV-->>WH: Webhook event (idempotent)
  WH-->>AV: 200 OK (store + reconcile)

Security + reliability checklist

Verify webhook signatures before parsing business fields.
Store and dedupe by event ID to guarantee idempotency.
Reject replayed events outside allowed timestamp drift.
Return 2xx only after durable write succeeds.
Retry transient failures with bounded backoff.
Process delayed events by comparing event time vs current state.
Route poison events to dead-letter queue for manual review.
Alert on repeated signature failures and high retry rates.

Handler pattern

verifySignature(rawBody, headers)
if duplicate(eventId): return 200
write event + state transition atomically
ack 200
async reconcile downstream systems