Webhook events & payloads

General Payload Structure

All webhook deliveries use a single, consistent JSON payload structure.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_123456789",
  "event_type": "pid.completed",
  "event_timestamp": "2026-01-22T06:40:00.000Z",
  "data": {}
}

Payload Fields

Field	Type	Description
version	string	Webhook payload version
tenant_id	string	ID of the tenant that triggered the event
event_id	string	Unique event identifier (stable across retries, safe for idempotency)
event_type	string	The event type name (e.g. pid.completed)
event_timestamp	string	ISO-8601 timestamp indicating when the event occurred
data	object	Event-specific payload (see event definitions below)

ℹ️ The event_type field always matches the value of the X-Agc-Event-Type request header.

Relationship Between Headers & Payload

Some metadata is available both in headers and in the payload for convenience and reliability.

Header	Payload Field
X-Agc-Version	version
X-Agc-Tenant-Id	tenant_id
X-Agc-Event-Id	event_id
X-Agc-Event-Type	event_type

The payload body should be treated as the authoritative source, while headers allow quick filtering, routing, and logging at the HTTP layer.

---

Event Types & Payloads

This section documents all webhook event types and the structure of the data object for each event.

Applicant Document Events

applicant_document.created

Triggered when an applicant document is created.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_doc_created_001",
  "event_type": "applicant_document.created",
  "event_timestamp": "2026-01-22T06:12:00.000Z",
  "data": {
    "id": "doc_123",
    "applicant_id": "applicant_456",
    "category": "passport"
  }
}

applicant_document.updated

Triggered when an applicant document is updated.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_doc_updated_002",
  "event_type": "applicant_document.updated",
  "event_timestamp": "2026-01-22T06:15:00.000Z",
  "data": {
    "id": "doc_123",
    "applicant_id": "applicant_456",
    "category": "passport"
  }
}

applicant_document.deleted

Triggered when an applicant document is deleted.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_doc_deleted_003",
  "event_type": "applicant_document.deleted",
  "event_timestamp": "2026-01-22T06:18:00.000Z",
  "data": {
    "id": "doc_123",
    "applicant_id": "applicant_456",
    "category": "passport"
  }
}

---

Compliance Events

compliance.cleared

Triggered when a compliance check has been cleared.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_compliance_010",
  "event_type": "compliance.cleared",
  "event_timestamp": "2026-01-22T06:20:00.000Z",
  "data": {
    "id": "cmp_789",
    "applicant_id": "applicant_456",
    "applicant_type": "applicant_main"
  }
}

---

Driver License Verification (DLV)

dlv.completed

Triggered when a driver license verification is completed.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_dlv_020",
  "event_type": "dlv.completed",
  "event_timestamp": "2026-01-22T06:25:00.000Z",
  "data": {
    "id": "dlv_321",
    "applicant_id": "applicant_456",
    "applicant_type": "applicant_main"
  }
}

---

Out of Wallet (OOW)

oow.completed

Triggered when an Out of Wallet Questionnaire is completed.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_oow_030",
  "event_type": "oow.completed",
  "event_timestamp": "2026-01-22T06:30:00.000Z",
  "data": {
    "id": "oow_654",
    "applicant_id": "applicant_456",
    "applicant_type": "applicant_main"
  }
}

---

One-Time Password (OTP)

otp.completed

Triggered when an OTP verification is completed.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_otp_040",
  "event_type": "otp.completed",
  "event_timestamp": "2026-01-22T06:35:00.000Z",
  "data": {
    "id": "otp_987",
    "applicant_id": "applicant_456",
    "applicant_type": "applicant_main"
  }
}

---

Precise ID (PID)

pid.completed

Triggered when a Precise ID flow is completed.

{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_pid_050",
  "event_type": "pid.completed",
  "event_timestamp": "2026-01-22T06:40:00.000Z",
  "data": {
    "id": "pid_111",
    "applicant_id": "applicant_456",
    "applicant_type": "applicant_main"
  }
}

---

Event Payload Reference

Common Fields

Field	Description
id	ID of the completed resource (document, verification, PID, etc.)
applicant_id	ID of the related applicant
applicant_type	Type of applicant (e.g. applicant_main, applicant_co)
category	Document category (documents only)

---

Important Notes

• The data field is event-specific and its structure depends on event_type
• Always validate the event using event_type before processing data
• Use event_id for idempotent processing
• event_timestamp represents the time the event occurred