# Verification webhooks

Verification events describe one individual verification from processing to a terminal result. All five names use the same `data` schema, so a handler can upsert one record by `verificationId` and branch on `type` and `status`.

## Lifecycle

| Event | When it fires | Recommended handling |
|---|---|---|
| `verification.started` | The verification enters processing. | Record the IDs and show a processing state. Do not treat it as a completed check. |
| `verification.completed` | The verification completes successfully. | Persist the result and continue the approved customer flow. |
| `verification.failed` | The check completes with a failed identity, data or biometric result. | Show the public `reason`; route according to your policy. |
| `verification.not_found` | The submitted identity cannot be found. | Ask the customer to verify the identifier or use another supported method. |
| `verification.error` | A verification service error stops processing. | Keep the customer retryable and use `reasonCode` for support diagnostics. |

## Complete successful payload

```json
{
  "version": "2026-08-11",
  "id": "evt_4d6628b920d940d48ae7ac2e",
  "type": "verification.completed",
  "createdAt": "2026-08-15T12:14:37.150Z",
  "deliveryId": "del_01j9verification01",
  "data": {
    "verificationId": "ver_sample0000000000",
    "requestId": "req_sample_verified",
    "externalId": "your_user_123",
    "workflowId": "wf_sample0000000000",
    "workflowVersion": 3,
    "status": "VERIFIED",
    "reason": null,
    "reasonCode": null,
    "verificationMethod": "sandbox",
    "assuranceLevel": null,
    "idType": "bvn",
    "country": "NG",
    "subjectType": "individual",
    "idNumber": "00000000001",
    "business": null,
    "questionnaire": null,
    "proofOfAddress": null,
    "nfc": null,
    "emailVerification": null,
    "phoneVerification": null,
    "deviceIntel": null,
    "userData": {
      "firstName": "Amina",
      "lastName": "Okafor",
      "middleName": null,
      "dateOfBirth": "1992-04-18",
      "gender": "female"
    },
    "facialMatch": true,
    "facialConfidence": 92,
    "dataMatch": true,
    "media": {
      "selfie": "/api/verifications/ver_sample0000000000/media/selfie",
      "livenessVideo": "/api/verifications/ver_sample0000000000/media/liveness-video"
    },
    "environment": "SANDBOX",
    "createdAt": "2026-08-15T12:14:31.004Z"
  }
}
```

Media values are absolute authenticated URLs in a live delivery. Fetch them with your API key. The illustrative relative paths above show the resource shape without exposing a deployment host.

## Event-specific examples

The repeated identity result fields follow the complete schema above. These fixtures show the fields that distinguish the other four event types.

```json
[
  {
    "version": "2026-08-11",
    "id": "evt_started_01",
    "type": "verification.started",
    "createdAt": "2026-08-15T12:14:31.004Z",
    "deliveryId": "del_started_01",
    "data": {
      "verificationId": "ver_sample0000000000",
      "requestId": "req_sample_pending",
      "externalId": "your_user_123",
      "workflowId": "wf_sample0000000000",
      "workflowVersion": 3,
      "status": "PENDING",
      "reason": null,
      "reasonCode": null,
      "verificationMethod": "sandbox",
      "assuranceLevel": null,
      "idType": "bvn",
      "country": "NG",
      "subjectType": "individual",
      "idNumber": "00000000001",
      "environment": "SANDBOX",
      "createdAt": "2026-08-15T12:14:31.004Z"
    }
  },
  {
    "version": "2026-08-11",
    "id": "evt_failed_01",
    "type": "verification.failed",
    "createdAt": "2026-08-15T12:15:03.421Z",
    "deliveryId": "del_failed_01",
    "data": {
      "verificationId": "ver_failed_01",
      "requestId": "req_sample_failed",
      "externalId": "your_user_124",
      "workflowId": "wf_sample0000000000",
      "workflowVersion": 3,
      "status": "FAILED",
      "reason": "The user's selfie does not match the photo on file with the government database (match confidence 38%, minimum 70% required).",
      "reasonCode": "selfie_mismatch",
      "verificationMethod": "sandbox",
      "assuranceLevel": null,
      "idType": "bvn",
      "country": "NG",
      "subjectType": "individual",
      "idNumber": "00000000002",
      "facialMatch": false,
      "facialConfidence": 38,
      "dataMatch": false,
      "environment": "SANDBOX",
      "createdAt": "2026-08-15T12:14:58.050Z"
    }
  },
  {
    "version": "2026-08-11",
    "id": "evt_not_found_01",
    "type": "verification.not_found",
    "createdAt": "2026-08-15T12:16:18.120Z",
    "deliveryId": "del_not_found_01",
    "data": {
      "verificationId": "ver_not_found_01",
      "requestId": "req_sample_not_found",
      "externalId": "your_user_125",
      "workflowId": null,
      "workflowVersion": null,
      "status": "NOT_FOUND",
      "reason": "The BVN number was not found in the government database.",
      "reasonCode": "identity_not_found",
      "verificationMethod": "gov_db",
      "assuranceLevel": null,
      "idType": "bvn",
      "country": "NG",
      "subjectType": "individual",
      "idNumber": "00000000003",
      "environment": "SANDBOX",
      "createdAt": "2026-08-15T12:16:11.004Z"
    }
  },
  {
    "version": "2026-08-11",
    "id": "evt_error_01",
    "type": "verification.error",
    "createdAt": "2026-08-15T12:17:40.902Z",
    "deliveryId": "del_error_01",
    "data": {
      "verificationId": "ver_error_01",
      "requestId": "req_sample_error",
      "externalId": "your_user_126",
      "workflowId": "wf_sample0000000000",
      "workflowVersion": 3,
      "status": "ERROR",
      "reason": "A temporary system error prevented this verification from being processed. No charge was applied.",
      "reasonCode": "system_error",
      "verificationMethod": "gov_db",
      "assuranceLevel": null,
      "idType": "bvn",
      "country": "NG",
      "subjectType": "individual",
      "idNumber": "00000000004",
      "environment": "SANDBOX",
      "createdAt": "2026-08-15T12:17:35.418Z"
    }
  }
]
```

## Field reference

| Field | Type | Nullable | Values and meaning |
|---|---|---:|---|
| `verificationId`, `requestId` | string | No | Stable verification and request identifiers. |
| `externalId` | string | Yes | Your customer reference supplied with the request. |
| `workflowId` | string | Yes | Published workflow that configured the run. |
| `workflowVersion` | integer | Yes | Exact published version that ran. Pair it with `workflowId`. |
| `status` | string | No | `PENDING`, `VERIFIED`, `FAILED`, `NOT_FOUND` or `ERROR`. |
| `reason`, `reasonCode` | string | Yes | Populated for failure outcomes. Codes are stable for routing; copy is suitable for display. |
| `verificationMethod` | string | Yes | `gov_db`, `document_ocr` or `sandbox`. Internal source names are deliberately hidden. |
| `assuranceLevel` | string | Yes | For a verified result: `chip`, `gov_db` or `document`. |
| `idType`, `country` | string | No | Submitted ID type and ISO 3166-1 alpha-2 country. |
| `subjectType` | string | No | `individual` or `business`. Business fields are documented separately. |
| `idNumber` | string | Yes | Submitted identifier where the method uses one. |
| `business` | object | Yes | Customer-safe registry result for business checks. |
| `questionnaire`, `proofOfAddress`, `nfc` | object | Yes | Workflow sub-results when those steps ran. |
| `emailVerification`, `phoneVerification` | object | Yes | Contact possession sub-results when enabled. |
| `deviceIntel` | object | Yes | Device, IP and soft-signal result when enabled. |
| `userData` | object | Yes | Individual identity fields. Null for a business subject. |
| `facialMatch`, `dataMatch` | boolean | Yes | Biometric and identity-data match results. |
| `facialConfidence` | number | Yes | Facial match confidence from the completed check. |
| `media` | object | Yes | Authenticated URLs for captured media. |
| `environment` | string | No | Environment that produced the event. |
| `createdAt` | ISO 8601 string | No | Verification record creation time. This differs from the envelope event time. |

## Related APIs and events

Read the verification resource when you need the latest state or full nested sub-results. `workflow.run.completed`, `credits.deducted`, `entity.created` and `identity.resolved` can refer to the same customer journey, but they are separate logical events and can arrive in a different order.

See [Authentication](https://trust.myaza.co/documentation/webhook-authentication/markdown) for signature verification and [Webhook Testing](https://trust.myaza.co/documentation/webhook-testing/markdown) for signed simulator delivery.