KYC Webhook

For each KYC status change, a webhook will be sent for the following statuses:

Status Table

STATUS ID	STATUS NAME
1	Awaiting Upload Documents
2	Awaiting Approval Documents
3	Approved
4	Pending Regularization
5	Canceled

Configuring the callback URL

Register the URL that receives the KYC webhooks for the kyc event, using the Webhook Setup API. You can query, update and remove it the same way.

The URL is registered per account: send account_id to register it for one of your subaccounts. The same URL can also receive other events — send kyc in the events list together with them.
Register a secret to receive the HMAC-SHA256 signature in every KYC webhook.
A subaccount without its own kyc webhook receives its KYC webhooks on its main account’s kyc webhook. See Subaccounts without a webhook.
When neither the account nor its main account has a kyc webhook registered, KYC webhooks keep being delivered to the callback URL previously configured by our Customer Experience team, if any, without the x-webhook-wp-* headers.

Registering, updating or removing a webhook may take up to 5 minutes to take effect. Until then, webhooks keep being delivered to the previous destination.

Example Payload

The webhook payload contains information about the KYC status change:

{
  "entity": "KYC",
  "id": 1670,
  "merchant_id": 516,
  "status": {
    "id": 1,
    "name": "Awaiting Upload Documents"
  },
  "metadata": {
    "blocked_person": {
      "name": "Test Kyc",
      "document": "99999919999979"
    }
  },
  "updated_at": "2025-07-13T14:00:13.6090002"
}

Example Headers

The webhook request includes the following headers:

{
  "Accept": "application/json",
  "Content-type": "application/json",
  "User-Agent": "WEpayments"
}

When a webhook is registered for the kyc event, the request also includes the x-webhook-wp-type and x-webhook-wp-timestamp headers, plus x-webhook-wp-signature when a secret is set:

{
  "Accept": "application/json",
  "Content-type": "application/json",
  "User-Agent": "WEpayments",
  "x-webhook-wp-type": "kyc",
  "x-webhook-wp-timestamp": "1790000000",
  "x-webhook-wp-signature": "5d41402abc4b2a76b9719d911017c592a3e1f5b8c4d6e7f8091a2b3c4d5e6f70"
}

See Webhook Signature to verify the signature.

Field Types

integer

Unique identifier for the KYC record.

integer

Merchant identifier associated with the KYC.

object

Object containing the current status of the KYC.

Show Status Object

integer

Status identifier.Possible values: 1, 2, 3, 4, 5

string

Name of the status.Possible values: Awaiting Upload Documents, Awaiting Approval Documents, Approved, Pending Regularization, Canceled

object

Additional metadata about the KYC process.

Show Metadata Object

object

Information about the person or entity in the KYC process.

Show Blocked Person Object

string

Name of the person or entity.

string

Document number (CPF or CNPJ).

string

Timestamp of when the KYC status was updated.Format: <date-time>

Webhook Status Flow

List KYC

List all KYC verifications

Get KYC By ID

Get KYC by ID

Get KYC By Document

Get KYC by document

Webhooks Guide

Learn about webhooks

Account

Banks

Payin

Payout

KYC

Markup

KYC Webhook

KYC Webhook

Status Table

Configuring the callback URL

Example Payload

Example Headers

Field Types

Webhook Status Flow

List KYC

Get KYC By ID

Get KYC By Document

Webhooks Guide

​KYC Webhook

​Status Table

​Configuring the callback URL

​Example Payload

​Example Headers

​Field Types

​Webhook Status Flow

​Related Resources

List KYC

Get KYC By ID

Get KYC By Document

Webhooks Guide

KYC Webhook

Status Table

Configuring the callback URL

Example Payload

Example Headers

Field Types

Webhook Status Flow

Related Resources