Receiving Webhooks
When you create a subscription via POST /v1/webhooks, Kiwify sends real-time notifications to your registered HTTPS endpoint.
How it works
- An event occurs on the account (transfer completed, QR code paid, deposit received, etc.).
- The dispatcher sends an HTTP POST to your registered URL.
- Your endpoint must respond with HTTP 2xx to acknowledge receipt.
- On failure, delivery is retried automatically (duplicates are possible).
Manage subscriptions using the Webhooks endpoints in the API reference. This guide documents what you receive on your server.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "CASHOUT.PIX.TRANSFERS.COMPLETED",
"version": "1.0",
"data": { },
"created_at": "2026-05-28T14:30:00Z"
}
| Field | Description |
|---|
id | UUID event identifier. Changes on every retry — do not use for deduplication. |
type | Concrete event type (e.g. CASHIN.DEPOSITS.RECEIVED). |
version | Envelope schema version (currently "1.0"). |
data | Event payload — structure depends on type. |
created_at | UTC timestamp (RFC 3339) when the event was generated. |
Deduplication
Do not use the envelope id for deduplication — it changes on every retry.
Use resource identifiers inside data:
| Event type | Deduplication key |
|---|
| Transfers | transfer_id + type |
| QR codes | qrcode_id + type |
| Deposits | transaction_id + type |
| Refunds | refund_id + type |
| Boleto | id + type |
Next steps
