Sign in

v5

latestOpenAPI 3.1.02026-07-262421791.5 MB
webhook-event
kyc-review

KYC review state change

Triggered when a KYC review state has changed.

{% admonition type="info" %} In previous versions, this event fired only when the overall KYC review state changed. In v5.0.0, it fires on every requirement or additional requirement state change, which may result in receiving more events. See data.resource.prevState and data.resource.requirementChanges for details on what changed. {% /admonition %}

  • Event type: kyc-reviews#state-change
  • Profile level subscriptions: Not Supported
  • Application level subscriptions: Supported

See the Webhooks guide for setup instructions, signature verification, and best practices.

postWebhookkyc-reviews#state-change

Headers

X-Signature-SHA256string

RSA-SHA256 signature of the request body, Base64 encoded. Verify this against the Wise public key to ensure the request is authentic and has not been tampered with.

X-Delivery-Idstring uuid

Unique identifier for this webhook delivery attempt.

X-Test-Notificationboolean

Present with the value true if this is a test notification sent to verify your callback URL during subscription setup.

Payload

OR
OR

Example payload

{
  "schema_version": "5.0.0",
  "subscription_id": "8df95817-8085-40aa-9bda-e3bf46e7a21a",
  "event_type": "kyc-reviews#state-change",
  "sent_at": "2024-09-03T16:29:42.123Z",
  "data": {
    "resource": {
      "id": "46e1a5c4-4a9b-4563-39d3-18174d3ac0f8",
      "state": "WAITING_CUSTOMER_INPUT",
      "prevState": "WAITING_CUSTOMER_INPUT",
      "profileId": 22016766,
      "requiredBy": "2024-09-03T16:22:02.258Z",
      "createdAt": "2024-09-03T16:22:02.258Z",
      "updatedAt": "2024-09-03T16:29:41.148Z",
      "triggerReferences": [
        {
          "type": "QUOTE",
          "triggerData": {
            "id": "ba83s43a-f623-46f0-956d-196c13e2ab01"
          }
        }
      ],
      "requirements": [
        [
          {
            "key": "ID_DOCUMENT",
            "state": "NOT_PROVIDED",
            "apiCollectionSupported": true,
            "additionalRequirements": [
              {
                "additionalRequirementId": "8b789c45-60ae-475d-b667-c8714db9a6a4",
                "key": "DOCUMENT_OR_WRITTEN_ANSWER",
                "state": "NOT_PROVIDED",
                "reasons": {
                  "errorCode": "EXPIRED",
                  "description": "The provided document or information has expired. A valid document is required.",
                  "dateTime": "2026-04-13T10:54:21.929314"
                },
                "attributes": {
                  "fields": {
                    "name": "John Smith",
                    "website": "https://example.com",
                    "businessName": "My Business Inc.",
                    "owningBusinessName": "Owning Business Inc.",
                    "markdownText": "Requirement details were unclear, *please* provide a clear scan where:\n\n*   All information is clearly readable\n*   The document is in colour"
                  },
                  "issues": [
                    "CANNOT_BE_SCREENSHOT",
                    "NEED_COLOUR_VERSION"
                  ]
                }
              }
            ],
            "versions": [
              {
                "version": "v1",
                "validUntil": "2026-06-30"
              }
            ]
          }
        ]
      ],
      "requirementChanges": [
        {
          "key": "ID_DOCUMENT",
          "newState": "IN_REVIEW",
          "prevState": "NOT_PROVIDED",
          "additionalRequirements": [
            {
              "additionalRequirementId": "8b789c45-60ae-475d-b667-c8714db9a6a4",
              "newState": "IN_REVIEW",
              "prevState": "NOT_PROVIDED"
            }
          ]
        }
      ]
    }
  }
}

Response

Return any 2xx status to acknowledge receipt of the event.

statusstring

Example response

{
  "status": "ok"
}