> ## 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.

# Receiving Webhooks

> Overview of webhook deliveries from the Conta Digital API

# Receiving Webhooks

When you create a subscription via `POST /v1/webhooks`, Kiwify sends real-time notifications to your registered HTTPS endpoint.

## How it works

1. An event occurs on the account (transfer completed, QR code paid, deposit received, etc.).
2. The dispatcher sends an **HTTP POST** to your registered URL.
3. Your endpoint must respond with **HTTP 2xx** to acknowledge receipt.
4. On failure, delivery is retried automatically (duplicates are possible).

<Info>
  Manage subscriptions using the **Webhooks** endpoints in the API reference. This guide documents what you **receive** on your server.
</Info>

## Envelope format

All deliveries use the same JSON envelope:

```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"
}
```

| 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](/en/api-reference/banking/webhook-events) — full subscription → delivery matrix
* [Payload structures](/en/api-reference/banking/webhook-payloads) — `data` field format per event
* [Headers & verification](/en/api-reference/banking/webhook-headers) — Ed25519 signature and HTTP headers