Identity Verification Webhook Resource

The Identity Verification webhook event is triggered when an identity verification process completes. This webhook notifies you when a child account's identity verification has been processed, allowing you to track KYC completion status in real-time.

📘
Identity verification webhooks are sent for child accounts under your account. The webhook payload includes the verification result and account details. To learn more about managing child accounts, see the Onboarding API guide.

Prerequisites

Before you rely on this webhook, complete these steps:

Register an HTTPS webhook endpoint that can receive POST requests. For setup details, see the Webhook Resource reference.
Set up child account onboarding and identity verification for the accounts you manage. To learn more, see the Onboarding API guide.
Configure your webhook handler to process account.identity_verification.passed and account.identity_verification.failed events.

Identity Verification Webhook Sample

The sample payloads below use placeholder identifiers.

Verification Passed

{
  "data": {
    "id": "evt_example_passed",
    "type": "event",
    "attributes": {
      "type": "account.identity_verification.passed",
      "livemode": true,
      "data": {
        "id": "verif_example_passed",
        "account_id": "org_example_account",
        "status": "completed",
        "result": "passed",
        "created_at": "2026-04-15T01:34:50Z",
        "expired_at": "2026-04-15T01:34:50Z"
      },
      "previous_data": {},
      "pending_webhooks": 1,
      "created_at": 1776149210,
      "updated_at": 1776149210
    }
  }
}

Verification Failed

{
  "data": {
    "id": "evt_example_failed",
    "type": "event",
    "attributes": {
      "type": "account.identity_verification.failed",
      "livemode": true,
      "data": {
        "id": "verif_example_failed",
        "account_id": "org_example_account",
        "status": "completed",
        "result": "failed",
        "created_at": "2026-04-15T01:34:50Z",
        "expired_at": "2026-04-15T01:34:50Z",
        "failure_reason": "Please retry again. Ensure the face is large and clearly centered (taking up at least half the image height), move closer to the camera, use good lighting without shadows, and capture in higher resolution with minimal background space."
      },
      "previous_data": {},
      "pending_webhooks": 1,
      "created_at": 1776149210,
      "updated_at": 1776149210
    }
  }
}

Webhook Event Properties

data.id string
A system-generated unique identifier for the webhook event. Prefixed with evt_.

data.type string
The type of webhook payload. Always event for identity verification webhooks.

data.attributes.type string
The specific event type that occurred. Can be:

account.identity_verification.passed - Identity verification completed successfully
account.identity_verification.failed - Identity verification was unsuccessful

data.attributes.livemode boolean
Indicates whether this event occurred in live mode. Currently always true. Sandbox/test mode support is coming soon.

data.attributes.data.id string
The unique identifier of the identity verification session. Prefixed with verif_.

data.attributes.data.type string
The type of resource contained in the webhook data. Always identity_verification.

data.attributes.data.attributes.account_id string
The unique identifier of the account (child merchant or consumer) that underwent identity verification. Prefixed with org_.

data.attributes.data.attributes.status string
The current status of the verification session. Can be:

pending - Verification session created but not yet started
in_progress - Verification is currently being processed
completed - Verification processing has finished

data.attributes.data.attributes.result string
The outcome of the identity verification. Can be:

pending - Verification has not yet been evaluated
passed - Identity verification was successful
failed - Identity verification was unsuccessful
invalid - Verification data was invalid or incomplete

data.attributes.data.attributes.created_at integer
Unix timestamp indicating when the verification session was created.

data.attributes.data.attributes.expired_at integer
Unix timestamp indicating when the verification session expires. By default, sessions expire 72 hours after creation. After expiration, the verification link becomes invalid.

Event Types

There are two identity verification webhook event types:

Event type	Description
`account.identity_verification.passed`	Triggered when identity verification completes successfully. The account has passed liveness checks and document verification.
`account.identity_verification.failed`	Triggered when identity verification fails. This can occur due to liveness check failure, document authentication issues, or incomplete data.

⚠️
When a verification fails, you should notify the account holder to retry the verification process. Failed verifications may require manual review depending on the failure reason.

Webhook Delivery

Identity verification webhooks are delivered to your registered webhook endpoints via HTTPS POST requests. For details on setting up webhook endpoints, verifying signatures, handling retries, and best practices, see the Webhook Resource reference.

Related Resources