> For the complete documentation index, see [llms.txt](https://docs.complycube.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.complycube.com/documentation/api-reference/other-resources/webhooks.md). # Webhooks Use the features of ComplyCube Webhooks to set up real-time notifications. ComplyCube uses [webhooks](https://en.wikipedia.org/wiki/Webhook) to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a [check](/documentation/api-reference/core-resources/checks.md) has concluded. You can configure webhook endpoints via the API or the Web Portal to be notified about events that happen in your ComplyCube account and related resources. Upon receiving a webhook notification, you should acknowledge success by responding with an HTTP `20x` response within 15 seconds. Otherwise, we will attempt to resend the notification up to 10 times according to an exponential back-off schedule. The first attempt will be made 60 seconds after the initial attempt; the second attempt will be made 120 seconds later; the third attempt will be made 480 seconds later, and so forth until all 10 attempts are exhausted. After which, the corresponding webhook will be disabled. You can quickly inspect webhook events with temporary endpoint URLs using free hosted services such as **. [Learn more about ComplyCube Webhooks](https://docs.complycube.com/documentation/guides/webhooks) ### The Webhook object | Attribute | Type | Description | | ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The unique identifier for the webhook. | | `description` | string | A description of what the webhook is used for. | | `url` | string | The URL of the webhook endpoint - **must be HTTPS**. | | `enabled` | boolean | Determines if the webhook should be active. | | `events` | array\[string] | The list of [event types](/documentation/api-reference/other-resources/webhooks.md#event-types) enabled for this webhook. `["*"]` indicates that all events will be published. | | `secret` | string | The endpoint’s secret used to generate [webhook](https://docs.complycube.com/documentation/guides/webhooks#verify-the-webhook-signatures-using-our-official-libraries) signatures. **Only** returned at creation. | | `createdAt` | string | The date and time when the webhook was created. | | `updatedAt` | string | The date and time when the webhook was updated. | ### Event Types | Event | Description | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `workflow.session.started` | A workflow session has been started. | | `workflow.session.cancelled` | A workflow session has been cancelled. | | `workflow.session.processing` | The customer has finished all steps in the workflow session, and the verification checks are now in progress. | | `workflow.session.completed` | A workflow session has been completed. | | `workflow.session.updated` | A workflow session outcome has been updated. | | `check.pending` | A check has been created and is in `pending` state. | | `check.completed` | A check has completed with **any** outcome. | | `check.completed.clear` | A check has completed with `clear` outcome. | | `check.completed.attention` | A check has completed with `attention` outcome. | | `check.completed.rejected` | A check has completed with `rejected` outcome. | | `check.completed.match_confirmed` | A check has completed with `match_confirmed` outcome. | | `check.monitoring.attention` | A monitoring check has completed with `attention` outcome. | | `check.failed` | A check has failed. | | `check.updated` | A check has been updated. | | `client.created` | A client has been created. | | `client.updated` | A client has been updated. | | `client.deleted` | A client has been deleted. | | `trigger.fired` | A lifecycle trigger executes a webhook action for a client. For triggers requiring approval, the event is generated after the execution is approved. | | `document.created` | A document has been created. | | `document.updated` | A document has been updated. | | `document.updated.image_uploaded` | A document has been updated with a new image. | | `document.updated.image_deleted` | A document has been updated as an image has been deleted. | | `document.deleted` | A document has been deleted. | | `address.created` | An address has been created. | | `address.updated` | An address has been updated. | | `address.deleted` | An address has been deleted. | ### The Event Object {% tabs %} {% tab title="Attributes" %} | Attribute | Type | Description | | -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The unique identifier for the event, which a webhook listener can use to bypass notification processing on a webhook notification sent more than once. | | `type` | string | The [event type](/documentation/api-reference/other-resources/webhooks.md#event-types) that initiated the event. | | `resourceType` | string | The type of the object contained within the payload, e.g. [check](/documentation/api-reference/core-resources/checks.md) object. | | `payload` | object | The key attributes of the object associated with this event. Also, see the [payload by resource type](/documentation/api-reference/other-resources/webhooks.md#payload-by-resource-type) table below. | | `createdAt` | string | The date and time when the webhook was created. | | {% endtab %} | | | {% tab title="Sample Object" %} ```json { "id": "5ed170fe99c81a0007b9a3d3", "type": "check.completed.clear", "resourceType": "check", "payload": { "id": "5ed3918fbf06f30008e552c9", "outcome": "clear", "status": "complete", "createdAt": "2020-01-01T11:14:23.964Z", "updatedAt": "2020-01-01T11:14:23.964Z" }, "createdAt": "2020-01-01T11:14:23.964Z" } ``` {% endtab %} {% endtabs %} #### Payload by resource type | Type | Payload | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | | | | | | The lifecycle trigger, execution, and client identifiers, together with the event that started the execution and its associated details. See [Lifecycle trigger payload](#lifecycle-trigger-payload) below. | #### Lifecycle trigger payload The `trigger.fired` event notifies your application when a [Lifecycle Trigger](/documentation/product-guides/compliance-studio/lifecycle-triggers.md) executes a **Send webhook** action for a client. Use it to connect periodic KYC reviews, document renewal, risk changes, and other lifecycle activity to your internal systems. The trigger must include a **Send webhook** action, and your webhook endpoint must subscribe to `trigger.fired`. For **Automatic** triggers, the event is generated when the webhook action runs. For **Needs approval** triggers, it is generated only after a reviewer approves the execution. Queuing an execution for approval does not generate this event. Each firing produces one event for subscribed endpoints. Webhook delivery retries can result in receiving the same event more than once. Use the top-level event `id` to identify duplicate deliveries. {% hint style="info" %} Receiving `trigger.fired` indicates that the **Send webhook** action ran. It does not confirm that other actions in the execution completed successfully or that the client completed a requested workflow. {% endhint %} **Example: date-based event (Document expiring)** This trigger fires 30 days before a client's passport expires, so `firedFor` is `before`. ```json { "id": "5eb1276d96be4a0008713af7", "type": "trigger.fired", "resourceType": "triggers", "payload": { "triggerId": "65f1c0a7e4b0a1b2c3d4e5f6", "triggerName": "Re-verify before ID expires", "triggerVersion": 3, "executionId": "65f1c0a7e4b0a1b2c3d4e5f7", "event": "document_expiring", "clientId": "5eb04fcd0f3e360008035eb1", "detail": "Passport expires in 30 days", "firedFor": "before", "checkId": "5eb1276d96be4a0008713af8", "documentType": "passport", "expiryDate": "2026-12-03" }, "createdAt": "2026-11-03T06:30:12.000Z" } ``` **Example: change-based event (Risk changed)** This trigger fires when the risk of a country linked to the client rises. Change-based events have no target date, so `firedFor` is always `on`. ```json { "id": "5eb1276d96be4a0008713b01", "type": "trigger.fired", "resourceType": "triggers", "payload": { "triggerId": "65f1c0a7e4b0a1b2c3d4e600", "triggerName": "Review when country risk rises", "triggerVersion": 1, "executionId": "65f1c0a7e4b0a1b2c3d4e601", "event": "risk_changed", "clientId": "5eb04fcd0f3e360008035eb1", "detail": "Country risk for RU changed from medium to high", "firedFor": "on", "subject": "country", "country": "RU", "from": "medium", "to": "high" }, "createdAt": "2026-11-06T10:14:03.000Z" } ``` **Common payload attributes** Every `trigger.fired` payload includes the following attributes:
AttributeTypeDescription
triggerIdstringThe identifier of the lifecycle trigger.
triggerNamestringThe name of the trigger.
triggerVersionnumberThe configuration version associated with this execution. Executions awaiting approval retain the version under which they were queued.
executionIdstringThe identifier of this trigger execution for the client.
eventstring

The lifecycle event that started the execution:

  • periodic_review
  • attestation_due
  • client_updated
  • monitoring_alert
  • risk_changed
  • stage_changed
  • check_outcome
  • check_validity
  • document_expiring
  • flow_incomplete.

See the event-specific attributes below.

clientIdstringThe identifier of the client associated with the execution.
detailstringA human-readable explanation of why the trigger fired. Use structured attributes for integration logic rather than parsing this text.
firedForstringThe timing of the execution relative to the target date: before, on, or after. For events without a target date, this value is on.
The top-level `type` is always `trigger.fired`. The payload’s `event` identifies the underlying lifecycle event, such as `document_expiring` or `risk_changed`. {% hint style="info" %} New attributes and new `event` values may be added over time. Ignore attributes you don't recognize, and don't fail on an `event` value you don't handle. {% endhint %} #### **Event-specific attributes** Additional payload attributes depend on the lifecycle event:
EventLifecycle eventAdditional attributes
periodic_reviewPeriodic review duedueDate, countedFrom, riskLevel
attestation_dueAttestation duedueDate, workflowTemplateId
client_updatedClient data changedfields
monitoring_alertNew screening matchcheckId, categories
risk_changedRisk changedsubject, from, to; also country when subject is country
stage_changedStage changedfrom, to; also byTriggerId when another trigger made the change
check_outcomeCheck completedcheckId, checkType, result
check_validityCheck validity expiringcheckId, checkType, validUntil
document_expiringDocument expiringcheckId, documentType, expiryDate
flow_incompleteFlow not completedworkflowTemplateId, flowSessionId, deadline
**Event-specific attribute reference** | Attribute | Type | Sent for | Description | | -------------------- | ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `checkId` | string | `check_outcome`, `check_validity`, `document_expiring`, `monitoring_alert` | The check the execution relates to. | | `checkType` | string | `check_outcome`, `check_validity` | The type of check: `proof_of_address_check`, `document_check`, `identity_check`, `standard_screening_check` or `extensive_screening_check`. | | `result` | string | `check_outcome` | The check's outcome: `clear`, `attention`, `rejected` or `match_confirmed`. `failed` means the check couldn't be completed. | | `validUntil` | date | `check_validity` | The date the check stops being treated as valid. | | `documentType` | string | `document_expiring` | The expiring document: `passport`, `driving_license`, `national_identity_card`, `residence_permit` or `visa`. | | `expiryDate` | date | `document_expiring` | The document's expiry date. | | `dueDate` | date | `periodic_review`, `attestation_due` | The date the review or attestation is due. | | `countedFrom` | date | `periodic_review` | The date the review interval is counted from. | | `riskLevel` | string | `periodic_review` | The client's risk level, which sets the review interval: `not_set`, `low`, `medium`, `high` or `very_high`. | | `workflowTemplateId` | string | `attestation_due`, `flow_incomplete` | The workflow the attestation or flow is for. | | `flowSessionId` | string | `flow_incomplete` | The flow session that wasn't completed. | | `deadline` | date | `flow_incomplete` | The date the flow was due to be completed by. | | `fields` | array of strings | `client_updated` | The client details that changed: `name`, `dob`, `nationality`, `country`, `address`, `email` or `mobile`. | | `categories` | array of strings | `monitoring_alert` | The categories of the new screening match: `pep`, `sanctionsLists`, `watchlist` or `adverseMedia`. | | `subject` | string | `risk_changed` | What changed: `client` (the client's risk level) or `country` (the risk of a country linked to the client). | | `country` | string | `risk_changed` | The country whose risk changed, as an ISO 3166-1 alpha-2 code. Sent when `subject` is `country`. | | `from`, `to` | string | `risk_changed` | The risk level before and after the change. For `client`: `not_set`, `low`, `medium`, `high` or `very_high`. For `country`: `low`, `medium`, `high` or `very_high`. | | `from`, `to` | string | `stage_changed` | The client's stage before and after the change: a built-in stage (`pending`, `onboarded`, `rejected` or `offboarded`), one of your own stage keys, or `none` when the client had no stage or it was cleared. | | `byTriggerId` | string | `stage_changed` | The trigger whose **Set client stage** action made the change. Absent when a team member or the API changed the stage. | For date-based events, a trigger can fire at multiple configured points around the same date. These are separate executions, each with its own `executionId`. For example, a document renewal trigger can generate one execution 30 days before expiration and another on the expiration date. These are separate lifecycle events, rather than duplicate deliveries of the same webhook event. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.complycube.com/documentation/api-reference/other-resources/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.