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.

Envelope format

All deliveries use the same JSON envelope:

{
  "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

Event types — full subscription → delivery matrix
Payload structures — data field format per event
Headers & verification — Ed25519 signature and HTTP headers

Documentation Index

​Receiving Webhooks

​How it works

​Envelope format

​Deduplication

​Next steps

Receiving Webhooks

How it works

Envelope format

Deduplication

Next steps