Webhooks

We forward webhook events to your HTTPS endpoint in real time. For each event type the payload structure is identical to the corresponding REST response — you don't need to learn a separate schema.

How it works

1. Configure your endpoint URL — via the Merchant Dashboard (Settings → Webhooks) or via PUT /api/v2/webhooks/config.
2. When an event occurs, we identify which merchant it belongs to and immediately POST it to your URL.
3. Each request includes an X-Webhook-Signature header (HMAC-SHA256) so you can verify authenticity.
4. Your server must respond with HTTP 2xx within 10 seconds. Delivery history is available in the dashboard and via GET /api/v2/webhooks/events.

Merchant Dashboard

Webhooks can be fully managed in the merchant cabinet under Settings → Webhooks, without touching the API.

Configuration

Fill in the form and click Create webhook:

Field	Description
Endpoint URL	Your publicly accessible HTTPS URL, e.g. https://yourapp.com/webhooks/incoming
Signing Secret (optional)	A secret string. We'll compute X-Webhook-Signature (HMAC-SHA256) on every request so you can verify it came from us
Event Types	Check All events to receive everything, or select specific types
Delivery enabled	Toggle to pause/resume delivery without deleting the config

Event log

The Webhooks page shows full delivery history — you can filter by status and event type to debug failed deliveries.

Event types

Event	Trigger
card_transaction	Transaction created / confirmed / cleared / status changed on a card
account_transaction	Account transaction created / confirmed / cleared / status changed
account_topup	Top-up received / confirmed / status changed on an account
card_state	Card created or status changed

Signature verification

Every POST we send includes:

X-Webhook-Signature: <hmac-sha256-hex>

Compute HMAC-SHA256 over the raw request body using your signing secret and compare it to the header value. Reject requests that do not match.

tip

If you didn't set a signing secret, you can skip signature verification — but we strongly recommend setting one in production.

Configuration API

Endpoint	Method	Description
GET /api/v2/webhooks/config	GET	Read current config
PUT /api/v2/webhooks/config	PUT	Set or update config
DELETE /api/v2/webhooks/config	DELETE	Remove config
GET /api/v2/webhooks/events	GET	Delivery history