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

# Recebendo Webhooks

> Visão geral de entregas de webhook da API Conta Digital

# Recebendo Webhooks

Quando você cria uma assinatura via `POST /v1/webhooks`, a Kiwify envia notificações em tempo real para o seu endpoint HTTPS registrado.

## Como funciona

1. Um evento ocorre na conta (transferência concluída, QR code pago, depósito recebido, etc.).
2. O dispatcher envia um **HTTP POST** para a URL registrada.
3. Seu endpoint deve responder com **HTTP 2xx** para confirmar recebimento.
4. Em caso de falha, a entrega é reenviada automaticamente (pode haver duplicatas).

<Info>
  Gerencie assinaturas com os endpoints em **Webhooks** na referência da API. Este guia documenta o que você **recebe** no seu servidor.
</Info>

## Formato do envelope

Todas as entregas usam o mesmo envelope JSON:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "CASHOUT.PIX.TRANSFERS.COMPLETED",
  "version": "1.0",
  "data": { },
  "created_at": "2026-05-28T14:30:00Z"
}
```

| Campo        | Descrição                                                                        |
| ------------ | -------------------------------------------------------------------------------- |
| `id`         | Identificador UUID do evento. **Muda a cada retry** — não use para deduplicação. |
| `type`       | Tipo concreto do evento (ex: `CASHIN.DEPOSITS.RECEIVED`).                        |
| `version`    | Versão do schema do envelope (atualmente `"1.0"`).                               |
| `data`       | Payload do evento — estrutura depende do `type`.                                 |
| `created_at` | Timestamp UTC (RFC 3339) de geração do evento.                                   |

## Deduplicação

**Não use o `id` do envelope** para deduplicação — ele muda a cada tentativa de reenvio.

Use os identificadores de recurso dentro de `data`:

| Tipo de evento | Chave de deduplicação     |
| -------------- | ------------------------- |
| Transferências | `transfer_id` + `type`    |
| QR codes       | `qrcode_id` + `type`      |
| Depósitos      | `transaction_id` + `type` |
| Estornos       | `refund_id` + `type`      |
| Boletos        | `id` + `type`             |

## Próximos passos

* [Tipos de evento](/api-reference/banking/webhook-events) — matriz completa de assinatura → entrega
* [Estruturas de payload](/api-reference/banking/webhook-payloads) — formato do campo `data` por evento
* [Headers e verificação](/api-reference/banking/webhook-headers) — assinatura Ed25519 e headers HTTP