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
Quando você cria uma assinatura viaPOST /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.
Formato do envelope
Todas as entregas usam o mesmo envelope JSON:| 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 oid 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 — matriz completa de assinatura → entrega
- Estruturas de payload — formato do campo
datapor evento - Headers e verificação — assinatura Ed25519 e headers HTTP