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

Direction	Endpoint	Who implements	Purpose
Kollect server to Merchant Server	Your webhookUrl	You	Kollect notifies your systems after updating payment state.

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

---

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 webhook URL:

• The payment was created with interface: kollect-server (this is the default for POST /sdk/server/create-payment).

• Your merchant has an active webhook configuration with a valid webhookUrl and signingSecret.

Expose your webhook here, navigate to webhook section and generate webhook signing secret.

See Registration & delivery for KYB and API prerequisites.

---

Delivery semantics

Topic	Behavior
HTTP method	POST
Body	JSON (see Payload & signature verification)
Timeout	Outbound client uses a 10 second timeout
Retries	No automatic retries in the current implementation; treat delivery as best-effort
Success	Kollect treats 2xx responses as success

If your endpoint returns non-2xx, Kollect logs the failure. Design your integration to reconcile using paymentId and internal order state if a webhook is missed.

---

Security model

Each request includes X-Kollect-Signature, an HMAC-SHA256 of the JSON payload using your webhook signing secret. You must verify this header before trusting the body. See Payload & signature verification.

---

Related pages

• Architecture & data flow

• Registration & delivery

• Payload & signature verification