# Business verification webhooks

These events connect a completed KYC or KYB journey to the durable entity, identity and workflow records created for it. They can arrive independently of `verification.completed`, so deduplicate each event by envelope `id` and join records by the IDs in `data`.

## Events and handling

| Event | When it fires | Recommended handling |
|---|---|---|
| `entity.created` | A successful Myaza verification creates an entity. | Store the entity ID against your customer. |
| `entity.imported` | An externally verified entity is created through an import or Identity API call. | Store its provenance and follow the import job if `jobId` exists. |
| `identity.resolved` | An entity is linked to a global identity. | Add the identity ID without replacing the entity ID. |
| `entity.reverification_due` | The entity reaches its re-verification due date. | Start a new check before `dueAt`. |
| `workflow.run.completed` | A workflow reaches a terminal customer outcome. | Persist the version, outcome and tags. |
| `workflow.run.failed` | A workflow stops because of an engine fault. | Keep the journey retryable and inspect the run. |
| `workflow.action` | A configured workflow webhook action executes. | Route the action by `nodeId`; do not infer a final outcome. |
| `key_person.completed` | A director or beneficial-owner verification resolves. | Update that person inside the parent business review. |

## Complete entity example

```json
{
  "version": "2026-08-11",
  "id": "evt_entity_created_01",
  "type": "entity.created",
  "createdAt": "2026-08-15T13:06:44.002Z",
  "deliveryId": "del_entity_created_01",
  "data": {
    "entityId": "ent_2405a1d091cf154b1ecfc9689e75f37b",
    "orgId": "org_01j9myaza",
    "environment": "SANDBOX",
    "externalUserId": "business_1048",
    "type": "business",
    "kycProvenance": "MYAZA_VERIFIED",
    "verificationId": "ver_business_1048",
    "createdAt": "2026-08-15T13:06:43.711Z"
  }
}
```

## Event-specific `data` contracts

Insert each object below into the shared V2 envelope. Optional fields appear only when the producing operation has them.

```json
[
  { "type": "entity.imported", "data": { "entityId": "ent_imported_01", "identityId": "idn_01", "externalUserId": "customer_882", "environment": "SANDBOX", "jobId": "imp_01" } },
  { "type": "identity.resolved", "data": { "entityId": "ent_imported_01", "identityId": "idn_01", "environment": "SANDBOX", "matchedExisting": true } },
  { "type": "entity.reverification_due", "data": { "entityId": "ent_2405a1d091cf154b1ecfc9689e75f37b", "externalUserId": "business_1048", "environment": "PRODUCTION", "dueAt": "2026-09-15T00:00:00.000Z" } },
  { "type": "workflow.run.completed", "data": { "runId": "wfr_01", "workflowId": "wf_kyb_01", "workflowVersion": 7, "verificationId": "ver_business_1048", "entityId": "ent_2405a1d091cf154b1ecfc9689e75f37b", "environment": "SANDBOX", "outcome": "APPROVE", "tags": ["registry-match", "screening-clear"], "completedAt": "2026-08-15T13:06:44.002Z" } },
  { "type": "workflow.run.failed", "data": { "runId": "wfr_02", "workflowId": "wf_kyb_01", "workflowVersion": 7, "verificationId": "ver_business_1049", "environment": "SANDBOX", "error": "A workflow action could not be completed.", "failedAt": "2026-08-15T13:11:04.192Z" } },
  { "type": "workflow.action", "data": { "runId": "wfr_01", "workflowId": "wf_kyb_01", "verificationId": "ver_business_1048", "entityId": "ent_2405a1d091cf154b1ecfc9689e75f37b", "nodeId": "node_notify_legal", "note": "Notify the compliance operations queue", "environment": "SANDBOX" } },
  { "type": "key_person.completed", "data": { "keyPersonId": "kp_01", "verificationId": "ver_business_1048", "personVerificationId": "ver_person_01", "role": "DIRECTOR", "isApplicant": false, "status": "VERIFIED", "environment": "SANDBOX" } }
]
```

## Field reference

| Field | Type | Nullable | Meaning |
|---|---|---:|---|
| `entityId`, `identityId` | string | `identityId` can be null | Organisation-scoped entity and resolved global identity IDs. |
| `externalUserId` | string | No when present | Your stable customer reference. |
| `type` | string | No | `individual` or `business`. |
| `kycProvenance` | string | No | Verification provenance, for example `MYAZA_VERIFIED`. |
| `workflowId`, `runId`, `verificationId` | string | Event-dependent | IDs for the exact journey. |
| `workflowVersion` | integer | Event-dependent | Published workflow version that ran. |
| `outcome` | string | Event-dependent | Terminal workflow outcome such as `APPROVE`, `DECLINE` or `REVIEW`. |
| `tags` | string[] | No on completion | Workflow-generated classification tags. |
| `role` | string | No for key people | Business relationship, for example `DIRECTOR`. |
| `status` | string | No for key people | Result status, for example `VERIFIED` or `FAILED`. |
| `environment` | string | No | `SANDBOX` or `PRODUCTION`. |
| `createdAt`, `completedAt`, `failedAt`, `dueAt` | ISO 8601 string | Event-dependent | Resource lifecycle time. |

Business verification result fields such as registry records, directors and ownership remain on the verification resource. Behaviour and reauthentication events are documented under [Event Monitoring](https://trust.myaza.co/documentation/webhook-event-monitoring/markdown).

## Related APIs and events

Use entity, verification and workflow-run read APIs for current state. Related events include `verification.completed`, `screening.completed`, `credits.deducted` and `risk.assessment.completed`. They are not guaranteed to arrive in that order.