> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byzantine.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer webhooks

> Customer onboarding (KYC/KYB) lifecycle webhook events.

Customer events track the KYC/KYB onboarding lifecycle of a customer. Subscribe to them to keep your onboarding UI and compliance workflows in sync.

## Populated fields

Each customer event populates `accountId` and, depending on the customer type, `userId` (individual) or `entityId` (entity). `beneficiaryId` is set when the event concerns a specific associated person of an entity. The `provider` field indicates the source of the change (for example `sumsub` or `bridge`).

## Event types

| Event                                             | Fires when                                                                         |
| ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `customer.created`                                | An individual/entity account is created (KYC/KYB submission started).              |
| `customer.under_review`                           | KYC/KYB is in progress.                                                            |
| `customer.awaiting_associated_person_information` | An entity customer is waiting for a beneficiary's or representative's information. |
| `customer.resubmission_requested`                 | Additional information or documents are required from the customer.                |
| `customer.active`                                 | Verification is approved; the account can transact.                                |
| `customer.rejected`                               | Verification was rejected.                                                         |

For the full meaning of each state, see [Verification statuses](/api-reference/verification-statuses).

## Example payload by event type

### `customer.created`

```json theme={null}
{
  "id": "b278e1f9-01fb-fd5a-b415-ceadcea59371",
  "eventType": "customer.created",
  "occurredAt": "2026-06-30T12:26:56.332244878Z",
  "livemode": true,
  "payloadVersion": 1,
  "integratorId": "a2d10a77-4e92-4b5f-c236-aef978975260",
  "accountId": "34158778-3bb4-d6b6-3b18-60413b83d7cb",
  "userId": "bd4ca296-067f-5847-5854-d054d84d4a62",
  "provider": "sumsub",
  "providerEventId": "db3960a8fc93af8da0a67c458b50d588",
  "data": {
    "customerType": "individual",
    "provider": "sumsub",
    "providerEventId": "db3960a8fc93af8da0a67c458b50d588",
    "reasonCodes": null,
    "reviewAnswer": null,
    "reviewRejectType": null,
    "sumsubApplicantId": "334ce71338ef9eae2312bcaf",
    "sumsubInspectionId": "334ce71338ef9eae2312bcaf",
    "sumsubReviewStatus": "init",
    "sumsubWebhookType": "applicantCreated",
    "verificationStatus": "under_review"
  }
}
```

### `customer.under_review`

```json theme={null}
{
  "id": "84160c37-bc5e-6a66-8e96-7743ffb7d933",
  "eventType": "customer.under_review",
  "occurredAt": "2026-06-30T13:18:29.838139831Z",
  "livemode": true,
  "payloadVersion": 1,
  "integratorId": "a2d10a77-4e92-4b5f-c236-aef978975260",
  "accountId": "e47d2ac4-bedc-6cee-a622-bfc39c00c1b9",
  "userId": "40c2d1d2-23a2-510e-aabf-b004995bd450",
  "provider": "sumsub",
  "providerEventId": "75b027242ee537c024a1320d91302856",
  "data": {
    "customerType": "individual",
    "provider": "sumsub",
    "providerEventId": "75b027242ee537c024a1320d91302856",
    "reasonCodes": null,
    "reviewAnswer": "GREEN",
    "reviewRejectType": null,
    "sumsubApplicantId": "ae95a70b080f57c4a0331b50",
    "sumsubInspectionId": "ae95a70b080f57c4a0331b50",
    "sumsubReviewStatus": "onHold",
    "sumsubWebhookType": "applicantOnHold",
    "verificationStatus": "under_review"
  }
}
```

### `customer.awaiting_associated_person_information`

```json theme={null}
{
  "id": "923db2c1-a246-7fc2-ac1e-80a41f7ae2e3",
  "eventType": "customer.awaiting_associated_person_information",
  "occurredAt": "2026-06-30T13:54:33.639484252Z",
  "livemode": true,
  "payloadVersion": 1,
  "integratorId": "a2d10a77-4e92-4b5f-c236-aef978975260",
  "accountId": "08873ea7-1fdb-9aa1-1103-d8d8250c48d6",
  "entityId": "48de5c25-114b-3ca8-9c3e-ce5a8882f35f",
  "provider": "sumsub",
  "providerEventId": "76af255a5ab7e7ea6f51c097d59f97db",
  "data": {
    "customerType": "entity",
    "provider": "sumsub",
    "providerEventId": "76af255a5ab7e7ea6f51c097d59f97db",
    "reasonCodes": [
      "NOT_ALL_CHECKS_COMPLETED"
    ],
    "reviewAnswer": "GREEN",
    "reviewRejectType": null,
    "sumsubApplicantId": "b000f2cb9974a87cc85ce070",
    "sumsubInspectionId": "b000f2cb9974a87cc85ce070",
    "sumsubReviewStatus": "awaitingUser",
    "sumsubWebhookType": "applicantAwaitingUser",
    "verificationStatus": "awaiting_associated_person_information"
  }
}
```

### `customer.resubmission_requested`

```json theme={null}
{
  "id": "c9e18f88-5b82-c884-09c3-f024717029c0",
  "eventType": "customer.resubmission_requested",
  "occurredAt": "2026-06-30T13:02:36.065663638Z",
  "livemode": true,
  "payloadVersion": 1,
  "integratorId": "a2d10a77-4e92-4b5f-c236-aef978975260",
  "accountId": "212f38c2-51ec-941d-2fec-fd05c463cc3d",
  "userId": "8b4cc5ab-e3b7-40bd-f4e8-378bcd1e39a7",
  "provider": "sumsub",
  "providerEventId": "599d26badc2e76b82884bc9d139e7419",
  "data": {
    "customerType": "individual",
    "provider": "sumsub",
    "providerEventId": "599d26badc2e76b82884bc9d139e7419",
    "reasonCodes": [
      "BAD_PROOF_OF_ADDRESS",
      "PROBLEMATIC_APPLICANT_DATA",
      "WRONG_ADDRESS"
    ],
    "reviewAnswer": "RED",
    "reviewRejectType": "RETRY",
    "sumsubApplicantId": "f7e5e932379c74f49d29ac19",
    "sumsubInspectionId": "f7e5e932379c74f49d29ac19",
    "sumsubReviewStatus": "completed",
    "sumsubWebhookType": "applicantReviewed",
    "verificationStatus": "resubmission_requested"
  }
}
```

### `customer.active`

```json theme={null}
{
  "id": "adc728e7-fdb9-3ce1-a1bf-36ff45178322",
  "eventType": "customer.active",
  "occurredAt": "2026-06-30T13:51:58.453021093Z",
  "livemode": true,
  "payloadVersion": 1,
  "integratorId": "a2d10a77-4e92-4b5f-c236-aef978975260",
  "accountId": "2e598259-4992-a7a4-a930-33bf1994f4d8",
  "userId": "944a0d48-dc02-a4b9-474c-259e05a64ba5",
  "provider": "sumsub",
  "providerEventId": "1988857e60296e36e2f1fb066be20e43",
  "data": {
    "customerType": "individual",
    "provider": "sumsub",
    "providerEventId": "1988857e60296e36e2f1fb066be20e43",
    "reasonCodes": null,
    "reviewAnswer": "GREEN",
    "reviewRejectType": null,
    "sumsubApplicantId": "00ed11e2cb6646ba6cc018ca",
    "sumsubInspectionId": "00ed11e2cb6646ba6cc018ca",
    "sumsubReviewStatus": "completed",
    "sumsubWebhookType": "applicantReviewed",
    "verificationStatus": "active"
  }
}
```

### `customer.rejected`

```json theme={null}
{
  "id": "78e51990-f219-558f-d301-054b1f3dd9a8",
  "eventType": "customer.rejected",
  "occurredAt": "2026-06-30T12:50:11.512839296Z",
  "livemode": true,
  "payloadVersion": 1,
  "integratorId": "a2d10a77-4e92-4b5f-c236-aef978975260",
  "accountId": "a6fbfc44-3071-604f-1e3a-57e63b67ecac",
  "userId": "b43c6126-b6a5-ffaf-7bea-7a1ef44a6048",
  "provider": "sumsub",
  "providerEventId": "36eb4739aa2311fb0cef97caed8626f4",
  "data": {
    "customerType": "individual",
    "provider": "sumsub",
    "providerEventId": "36eb4739aa2311fb0cef97caed8626f4",
    "reasonCodes": [
      "INCORRECT_SOCIAL_NUMBER",
      "COMPROMISED_PERSONS"
    ],
    "reviewAnswer": "RED",
    "reviewRejectType": "FINAL",
    "sumsubApplicantId": "c68396da4e0fa1819f0ee0d0",
    "sumsubInspectionId": "c68396da4e0fa1819f0ee0d0",
    "sumsubReviewStatus": "completed",
    "sumsubWebhookType": "applicantReviewed",
    "verificationStatus": "rejected"
  }
}
```