Webhooks

Webhooks notify your server when checkout state changes. Register webhooks in the merchant platform (URL, subscribed events, secret). This page describes what your server must implement.

Platform setup

In the merchant platform:

Add an HTTPS endpoint URL (publicly reachable).

Choose subscribed events (start with checkout.paid and checkout.failed).

Copy the webhook secret and store it on your server for signature verification.

Use Send test or delivery logs in the platform to debug.

Webhook management APIs are intentionally not part of the public Checkout API reference.

Incoming request

KutanaPay sends POST to your URL with headers:

Payload envelope

{
  "version": "v1",
  "event_type": "checkout.paid",
  "timestamp": "2025-11-17T12:34:56Z",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": { }
}

data holds event-specific fields (checkout id, amount, currency, status, customer email when present).

Checkout events (common)

See Webhook event reference for the full catalog, field tables, and a sample checkout.paid payload.

Start with: checkout.paid, checkout.approved, checkout.rejected, and optionally checkout.created.

Verify the signature

Always verify X-Webhook-Signature before trusting the body.

Read the raw request body as bytes or UTF-8 string (before JSON parsing).

Header format: sha256=<hex>.

Compute HMAC-SHA256 of the raw body using your webhook secret.

Compare with constant-time equality (hmac.compare_digest in Python).

Python

Use the raw body from the request (request.get_data(as_text=True) in Flask, await request.body() in FastAPI before parsing JSON).

Node.js

Handler checklist

Verify signature; return 401 if invalid.

Optionally reject stale timestamp (replay protection).

Dedupe using idempotency_key (store processed keys).

Return 2xx quickly; heavy work can run async.

Use 5xx only for temporary failures (KutanaPay retries). Use 4xx for permanent rejections.

Retries

Failed deliveries are retried with backoff. Make handlers idempotent.

Troubleshooting

Issue	Check
Signature fails	Raw body vs re-serialized JSON; wrong secret; header name case
No deliveries	HTTPS URL; firewall; URL reachable from internet
Disabled webhook	Platform delivery logs after repeated failures

Platform setup#

Incoming request#

Payload envelope#

Checkout events (common)#

Verify the signature#

Python#

Node.js#

Handler checklist#

Retries#

Troubleshooting#