Customer webhooks

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

Every customer event carries the ids it concerns in the envelope’s related block. accountId is always set, together with userId for an individual customer or entityId for an entity. beneficiaryId is set when the event concerns one specific associated person of an entity. Keys that do not apply are null rather than absent.

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.
`customer.deactivated`	A previously active customer was deactivated and can no longer transact.

For the full meaning of each state, see Verification statuses.

The `data` object

Every customer.* event carries the same three keys under data. All three are always present - they are set to null when they do not apply, so a strict schema validator never sees keys appear and disappear between event types.

Key	Set when	Contents
`customer`	Always	The KYC/KYB subject: `accountId`, `customerType` (`individual` or `entity`), `userId` or `entityId`, `name`, `email`, `verificationStatus`, `createdAt`.
`beneficiary`	UBO-scoped events only	The associated person the event is about: `beneficiaryId`, `firstName`, `lastName`, `verificationStatus`. `null` otherwise.
`reasonCodes`	`resubmission_requested` and `rejected`	Array of reason codes explaining the decision. `null` otherwise.

name is "FirstName LastName" for an individual and the company name for an entity. email is the user’s email for an individual, or the company email declared at KYB for an entity - null when the entity declared none.

Example payload by event type

`customer.created`

{
  "id": "b278e1f9-01fb-fd5a-b415-ceadcea59371",
  "type": "customer.created",
  "occurredAt": "2026-06-30T12:26:56.332244878Z",
  "livemode": true,
  "payloadVersion": 1,
  "related": {
    "accountId": "34158778-3bb4-d6b6-3b18-60413b83d7cb",
    "userId": "bd4ca296-067f-5847-5854-d054d84d4a62",
    "entityId": null,
    "beneficiaryId": null,
    "transactionId": null
  },
  "data": {
    "customer": {
      "accountId": "34158778-3bb4-d6b6-3b18-60413b83d7cb",
      "customerType": "individual",
      "userId": "bd4ca296-067f-5847-5854-d054d84d4a62",
      "entityId": null,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "verificationStatus": "under_review",
      "createdAt": "2026-06-30T12:26:56.101877000Z"
    },
    "beneficiary": null,
    "reasonCodes": null
  }
}

`customer.under_review`

{
  "id": "84160c37-bc5e-6a66-8e96-7743ffb7d933",
  "type": "customer.under_review",
  "occurredAt": "2026-06-30T13:18:29.838139831Z",
  "livemode": true,
  "payloadVersion": 1,
  "related": {
    "accountId": "e47d2ac4-bedc-6cee-a622-bfc39c00c1b9",
    "userId": "40c2d1d2-23a2-510e-aabf-b004995bd450",
    "entityId": null,
    "beneficiaryId": null,
    "transactionId": null
  },
  "data": {
    "customer": {
      "accountId": "e47d2ac4-bedc-6cee-a622-bfc39c00c1b9",
      "customerType": "individual",
      "userId": "40c2d1d2-23a2-510e-aabf-b004995bd450",
      "entityId": null,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "verificationStatus": "under_review",
      "createdAt": "2026-06-30T12:26:56.101877000Z"
    },
    "beneficiary": null,
    "reasonCodes": null
  }
}

`customer.awaiting_associated_person_information`

An entity event scoped to one associated person: related.beneficiaryId is set, and data.beneficiary carries that person’s own verification status.

{
  "id": "923db2c1-a246-7fc2-ac1e-80a41f7ae2e3",
  "type": "customer.awaiting_associated_person_information",
  "occurredAt": "2026-06-30T13:54:33.639484252Z",
  "livemode": true,
  "payloadVersion": 1,
  "related": {
    "accountId": "08873ea7-1fdb-9aa1-1103-d8d8250c48d6",
    "userId": null,
    "entityId": "48de5c25-114b-3ca8-9c3e-ce5a8882f35f",
    "beneficiaryId": "6f2a11d0-3c8e-4a52-9f77-1b0d5c8e4a31",
    "transactionId": null
  },
  "data": {
    "customer": {
      "accountId": "08873ea7-1fdb-9aa1-1103-d8d8250c48d6",
      "customerType": "entity",
      "userId": null,
      "entityId": "48de5c25-114b-3ca8-9c3e-ce5a8882f35f",
      "name": "Analytical Engines Ltd",
      "email": "compliance@example.com",
      "verificationStatus": "awaiting_associated_person_information",
      "createdAt": "2026-06-29T09:12:04.771003000Z"
    },
    "beneficiary": {
      "beneficiaryId": "6f2a11d0-3c8e-4a52-9f77-1b0d5c8e4a31",
      "firstName": "Charles",
      "lastName": "Babbage",
      "verificationStatus": "awaiting_information"
    },
    "reasonCodes": null
  }
}

`customer.resubmission_requested`

{
  "id": "c9e18f88-5b82-c884-09c3-f024717029c0",
  "type": "customer.resubmission_requested",
  "occurredAt": "2026-06-30T13:02:36.065663638Z",
  "livemode": true,
  "payloadVersion": 1,
  "related": {
    "accountId": "212f38c2-51ec-941d-2fec-fd05c463cc3d",
    "userId": "8b4cc5ab-e3b7-40bd-f4e8-378bcd1e39a7",
    "entityId": null,
    "beneficiaryId": null,
    "transactionId": null
  },
  "data": {
    "customer": {
      "accountId": "212f38c2-51ec-941d-2fec-fd05c463cc3d",
      "customerType": "individual",
      "userId": "8b4cc5ab-e3b7-40bd-f4e8-378bcd1e39a7",
      "entityId": null,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "verificationStatus": "resubmission_requested",
      "createdAt": "2026-06-30T12:26:56.101877000Z"
    },
    "beneficiary": null,
    "reasonCodes": [
      "BAD_PROOF_OF_ADDRESS",
      "PROBLEMATIC_APPLICANT_DATA",
      "WRONG_ADDRESS"
    ]
  }
}

`customer.active`

{
  "id": "adc728e7-fdb9-3ce1-a1bf-36ff45178322",
  "type": "customer.active",
  "occurredAt": "2026-06-30T13:51:58.453021093Z",
  "livemode": true,
  "payloadVersion": 1,
  "related": {
    "accountId": "2e598259-4992-a7a4-a930-33bf1994f4d8",
    "userId": "944a0d48-dc02-a4b9-474c-259e05a64ba5",
    "entityId": null,
    "beneficiaryId": null,
    "transactionId": null
  },
  "data": {
    "customer": {
      "accountId": "2e598259-4992-a7a4-a930-33bf1994f4d8",
      "customerType": "individual",
      "userId": "944a0d48-dc02-a4b9-474c-259e05a64ba5",
      "entityId": null,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "verificationStatus": "active",
      "createdAt": "2026-06-30T12:26:56.101877000Z"
    },
    "beneficiary": null,
    "reasonCodes": null
  }
}

`customer.rejected`

{
  "id": "78e51990-f219-558f-d301-054b1f3dd9a8",
  "type": "customer.rejected",
  "occurredAt": "2026-06-30T12:50:11.512839296Z",
  "livemode": true,
  "payloadVersion": 1,
  "related": {
    "accountId": "a6fbfc44-3071-604f-1e3a-57e63b67ecac",
    "userId": "b43c6126-b6a5-ffaf-7bea-7a1ef44a6048",
    "entityId": null,
    "beneficiaryId": null,
    "transactionId": null
  },
  "data": {
    "customer": {
      "accountId": "a6fbfc44-3071-604f-1e3a-57e63b67ecac",
      "customerType": "individual",
      "userId": "b43c6126-b6a5-ffaf-7bea-7a1ef44a6048",
      "entityId": null,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "verificationStatus": "rejected",
      "createdAt": "2026-06-30T12:26:56.101877000Z"
    },
    "beneficiary": null,
    "reasonCodes": [
      "INCORRECT_SOCIAL_NUMBER",
      "COMPROMISED_PERSONS"
    ]
  }
}

`customer.deactivated`

{
  "id": "1d0c4b7a-9e33-4f18-b0a5-2c7e19f4d8b6",
  "type": "customer.deactivated",
  "occurredAt": "2026-07-02T08:14:22.004311000Z",
  "livemode": true,
  "payloadVersion": 1,
  "related": {
    "accountId": "2e598259-4992-a7a4-a930-33bf1994f4d8",
    "userId": "944a0d48-dc02-a4b9-474c-259e05a64ba5",
    "entityId": null,
    "beneficiaryId": null,
    "transactionId": null
  },
  "data": {
    "customer": {
      "accountId": "2e598259-4992-a7a4-a930-33bf1994f4d8",
      "customerType": "individual",
      "userId": "944a0d48-dc02-a4b9-474c-259e05a64ba5",
      "entityId": null,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "verificationStatus": "inactive",
      "createdAt": "2026-06-30T12:26:56.101877000Z"
    },
    "beneficiary": null,
    "reasonCodes": null
  }
}

Integrator API

API endpoints

Populated fields

Event types

The `data` object

Example payload by event type

`customer.created`

`customer.under_review`

`customer.awaiting_associated_person_information`

`customer.resubmission_requested`

`customer.active`

`customer.rejected`

`customer.deactivated`

​Populated fields

​Event types

​The data object

​Example payload by event type

​customer.created

​customer.under_review

​customer.awaiting_associated_person_information

​customer.resubmission_requested

​customer.active

​customer.rejected

​customer.deactivated

Populated fields

Event types

The `data` object

Example payload by event type

`customer.created`

`customer.under_review`

`customer.awaiting_associated_person_information`

`customer.resubmission_requested`

`customer.active`

`customer.rejected`

`customer.deactivated`