> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC Webhook

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

# 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                    |

<Note>
  The callback URL used is the same for all KYC processes. To configure a new callback URL, you need to contact the Customer Experience team.
</Note>

## Example Payload

The webhook payload contains information about the KYC status change:

```json theme={null}
{
  "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:

```json theme={null}
{
  "Accept": "application/json",
  "Content-type": "application/json",
  "User-Agent": "WEPayments"
}
```

## Field Types

<ResponseField name="id" type="integer">
  Unique identifier for the KYC record.
</ResponseField>

<ResponseField name="merchant_id" type="integer">
  Merchant identifier associated with the KYC.
</ResponseField>

<ResponseField name="status" type="object">
  Object containing the current status of the KYC.

  <Expandable title="Status Object">
    <ResponseField name="id" type="integer">
      Status identifier.

      Possible values: `1`, `2`, `3`, `4`, `5`
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the status.

      Possible values: `Awaiting Upload Documents`, `Awaiting Approval Documents`, `Approved`, `Pending Regularization`, `Canceled`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata about the KYC process.

  <Expandable title="Metadata Object">
    <ResponseField name="blocked_person" type="object">
      Information about the person or entity in the KYC process.

      <Expandable title="Blocked Person Object">
        <ResponseField name="name" type="string">
          Name of the person or entity.
        </ResponseField>

        <ResponseField name="document" type="string">
          Document number (CPF or CNPJ).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="updated_at" type="string">
  Timestamp of when the KYC status was updated.

  Format: `<date-time>`
</ResponseField>

## Webhook Status Flow

```mermaid theme={null}
graph TD
    A[KYC Created] --> B[1 - Awaiting Upload Documents]
    B -->|Documents Uploaded| C[2 - Awaiting Approval Documents]
    C -->|Review Complete| D{Approved?}
    D -->|Yes| E[3 - Approved]
    D -->|Issues Found| F[4 - Pending Regularization]
    F -->|Regularized| C
    B -->|Canceled| G[5 - Canceled]
    C -->|Canceled| G
    
    B -.->|Webhook Sent| H[Your Server]
    C -.->|Webhook Sent| H
    E -.->|Webhook Sent| H
    F -.->|Webhook Sent| H
    G -.->|Webhook Sent| H
```

## Related Resources

<CardGroup cols={2}>
  <Card title="List KYC" icon="list" href="/api-reference/kyc/list-kyc">
    List all KYC verifications
  </Card>

  <Card title="Get KYC By ID" icon="magnifying-glass" href="/api-reference/kyc/get">
    Get KYC by ID
  </Card>

  <Card title="Get KYC By Document" icon="file-search" href="/api-reference/kyc/get-by-document">
    Get KYC by document
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/concepts/webhooks">
    Learn about webhooks
  </Card>
</CardGroup>