Skip to navigation
Webhook event reference

Business verification

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

EventWhen it firesRecommended handling
entity.createdA successful Toden verification creates an entity.Store the entity ID against your customer.
entity.importedAn externally verified entity is created through an import or Identity API call.Store its provenance and follow the import job if jobId exists.
identity.resolvedAn entity is linked to a global identity.Add the identity ID without replacing the entity ID.
entity.reverification_dueThe entity reaches its re-verification due date.Start a new check before dueAt.
workflow.run.completedA workflow reaches a terminal customer outcome.Persist the version, outcome and tags.
workflow.run.failedA workflow stops because of an engine fault.Keep the journey retryable and inspect the run.
workflow.actionA configured workflow webhook action executes.Route the action by nodeId; do not infer a final outcome.
key_person.completedA director or beneficial-owner verification resolves.Update that person inside the parent business review.

Complete entity example

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

[
  { "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

FieldTypeNullableMeaning
entityId, identityIdstringidentityId can be nullOrganisation-scoped entity and resolved global identity IDs.
externalUserIdstringNo when presentYour stable customer reference.
typestringNoindividual or business.
kycProvenancestringNoVerification provenance, for example MYAZA_VERIFIED.
workflowId, runId, verificationIdstringEvent-dependentIDs for the exact journey.
workflowVersionintegerEvent-dependentPublished workflow version that ran.
outcomestringEvent-dependentTerminal workflow outcome such as APPROVE, DECLINE or REVIEW.
tagsstring[]No on completionWorkflow-generated classification tags.
rolestringNo for key peopleBusiness relationship, for example DIRECTOR.
statusstringNo for key peopleResult status, for example VERIFIED or FAILED.
environmentstringNoSANDBOX or PRODUCTION.
createdAt, completedAt, failedAt, dueAtISO 8601 stringEvent-dependentResource 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.

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.