> For the complete documentation index, see [llms.txt](https://kreatorverse-2.gitbook.io/kollect-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kreatorverse-2.gitbook.io/kollect-documentation/webhook-overview.md).

# Webhook Overview

Kollect can notify **your backend** when a payment reaches a terminal or important state by sending an **HTTP POST** to a URL you configure. This page describes **outbound** webhooks (Kollect → merchant).

***

## Two different webhook directions

<table><thead><tr><th width="187">Direction</th><th>Endpoint</th><th>Who implements</th><th>Purpose</th></tr></thead><tbody><tr><td><strong>Kollect server to Merchant Server</strong></td><td>Your <code>webhookUrl</code></td><td><strong>You</strong></td><td>Kollect notifies your systems after updating payment state.</td></tr></tbody></table>

**Integrators** only implement the **outbound** receiver. You need to setup recieving `webhookUrl` in your server.

***

## Webhook scopes

Webhooks are registered **per event type (`scope`)**, not one URL for your whole account. This documentation set covers the **`invoice_settlement`** scope — the events fired for payments created through `POST /sdk/server/create-payment`. (A separate `fiat_settlement` scope exists for Kollect's fiat off-ramp product; it is unrelated to the S2S invoice flow and out of scope for this guide.)

You can register a different `webhookUrl` — and a different signing secret — per scope. See [Registration & delivery](/kollect-documentation/webhook-overview/registration-and-delivery.md).

***

## When outbound webhooks fire

After Kollect processes a Smart Contract event (`payment.confirmed` or `payment.failed`), it updates the **invoice** and **payment** in the database. If **all** of the following hold, Kollect sends an outbound POST to your registered `invoice_settlement` webhook URL:

* The payment was created with **`interface: kollect-server`** (this is the **default** for `POST /sdk/server/create-payment` — see the warning on [Create payment URL](/kollect-documentation/api-reference/create-payment.md) if you override it).
* Your merchant has an **active** `invoice_settlement` webhook configuration with a valid **`webhookUrl`** and **`signingSecret`**.

Expose your webhook [here](https://kollect-stage.kreatorverse.com/profile), navigate to webhook section and generate webhook signing secret.

See [Registration & delivery](/kollect-documentation/webhook-overview/registration-and-delivery.md) for KYB and API prerequisites.

***

## Delivery semantics

| Topic           | Behavior                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **HTTP method** | `POST`                                                                                                                          |
| **Body**        | JSON (see [Payload & signature verification](/kollect-documentation/webhook-overview/payload-and-verification.md))              |
| **Timeout**     | **10 seconds** per attempt                                                                                                      |
| **Retries**     | Up to **4 attempts total** (1 initial + 3 retries) with backoff of **2s, 4s, 8s** between attempts, on network error or non-2xx |
| **Success**     | Kollect treats **2xx** responses as success and stops retrying                                                                  |

Delivery is **at-least-once**: a retry can redeliver an event your server already processed if your first response wasn't 2xx in time. Every payload carries a stable **`eventId`** — use it to dedupe (see [Payload & signature verification](/kollect-documentation/webhook-overview/payload-and-verification.md)). If your endpoint still returns non-2xx after all attempts, Kollect logs the failure and stops; design your integration to **reconcile** using `paymentId` and internal order state if a webhook is ultimately missed.

***

## Security model

Each request includes **`x-kollect-signature`** (raw hex HMAC) and **`x-kollect-signature-v2`** (`sha256=<hex>` prefixed) — both carry the same HMAC-SHA256 of the JSON payload using your **webhook signing secret**, sent in two formats for compatibility. Verify either one before trusting the body. See [Payload & signature verification](/kollect-documentation/webhook-overview/payload-and-verification.md).

***

## Related pages

* [Architecture & data flow](/kollect-documentation/introduction/architecture-and-data-flow.md)
* [Registration & delivery](/kollect-documentation/webhook-overview/registration-and-delivery.md)
* [Payload & signature verification](/kollect-documentation/webhook-overview/payload-and-verification.md)