# Webhook events & payloads

## General Payload Structure

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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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"
  }
}
```

---

### FastApp Events

#### `fastapp.submitted`

Triggered when an applicant submits a FastApp.

```json
{
  "version": "1.0",
  "tenant_id": "tenant_abc",
  "event_id": "evt_fastapp_025",
  "event_type": "fastapp.submitted",
  "event_timestamp": "2026-01-22T06:28:00.000Z",
  "data": {
    "applicant_id": "applicant_456",
    "fastapp_id": "fastapp_789"
  }
}
```

---

### Out of Wallet (OOW)

#### `oow.completed`

Triggered when an Out of Wallet Questionnaire is completed.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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)                               |
| `fastapp_id`     | ID of the FastApp integration (FastApp events 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

Source: https://apidocs.agilitycredit.com/webhooks/events-and-payloads