Skip to main content

Webhooks & Callbacks

Webhooks let the platform push notifications to the Company's backend instead of it polling. They cover both the result of a verification and ongoing changes to records. Webhooks are optional — a Company with no configured URLs can rely on polling the Customer API instead.

What gets delivered​

Event familyFires when
Workflow resultA verification completes — the terminal state and its reason.
Workflow eventA workflow explicitly emits a Company-defined event mid-flow or at an outcome (custom data payload).
Record actionA back-office operator changes a record — accept, reject, reset to review, blocklist, anonymize, merge, edit fields.

Configuration​

Companies register one or more webhook URLs in the dashboard. Each URL has its own signing secret and an optional event-type filter, so different systems can receive different subsets. See Administration → Integration Settings.

Envelope​

Every delivery shares a common envelope:

{
  "eventId": "…",
  "eventType": "record.action",
  "tenantId": "…",
  "occurredAt": "2026-01-01T12:00:00Z",
  "payload": { }
}

Payloads are diff-only — they carry what changed (transition from → to, actor, reason), not full snapshots. Fetch the full record from the Customer API when needed. Raw images are never included.

Verifying authenticity​

Each request is signed with an HMAC over the body using the URL's secret, sent in a signature header (e.g. X-IDV-Signature: sha256=<hex>). The receiver recomputes the HMAC and compares before trusting the payload.

Delivery guarantees​

PropertyBehavior
At-least-onceDeliveries retry over a 24-hour window with exponential backoff.
Retryable5xx, 408, 429 are retried; other 4xx are treated as permanent.
IdempotencyDe-duplicate on eventId — the same event may arrive more than once.
OrderingBest-effort per record; do not assume global order — sort on occurredAt if strict order matters.
Dead-letterAfter retries are exhausted, the delivery is recorded as failed and can be replayed from the dashboard; the admin is notified.

See also​