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.

Prerequisites

Before you rely on this webhook, complete these steps:

1. Register an HTTPS webhook endpoint that can receive POST requests. For setup details, see the Webhook Resource reference.
2. Set up child account onboarding and identity verification for the accounts you manage. To learn more, see the Onboarding API guide.
3. 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:

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

• Webhooks Overview
• Onboarding API
• Account Resource