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
- Um evento ocorre na conta (transferência concluída, QR code pago, depósito recebido, etc.).
- O dispatcher envia um HTTP POST para a URL registrada.
- Seu endpoint deve responder com HTTP 2xx para confirmar recebimento.
- Em caso de falha, a entrega é reenviada automaticamente (pode haver duplicatas).
Gerencie assinaturas com os endpoints em Webhooks na referência da API. Este guia documenta o que você recebe no seu servidor.
{
"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
