Skip to main content
Understand how the Baanx notification service works and get your endpoint ready to receive events.

​
What are Webhooks?

The Baanx Notification Service delivers real-time webhook notifications to your HTTPS endpoints when events occur in the platform. Instead of polling for changes, your application is called automatically when something happens — such as a user completing KYC, a card being activated, or a transaction clearing.

Secure Delivery

HMAC-SHA256 signed requests let you verify every delivery is genuinely from Baanx

Replay Protection

Timestamp-based validation prevents replayed or stale requests from being accepted

Automatic Retries

Exponential backoff retries ensure delivery even through transient failures

Idempotent Events

Every event has a unique event_id so your endpoint can safely handle duplicates

​
Prerequisites

To receive webhooks from Baanx you need:
  1. A publicly accessible HTTPS endpoint that can receive POST requests
  2. A webhook subscription configured with Baanx
  3. The ability to verify HMAC-SHA256 signatures in your server-side code
Only HTTPS endpoints are accepted. Plain HTTP URLs will be rejected.

​
Quick Start

1

Provide your endpoint URL

Share your webhook endpoint URL with Baanx and specify which event types you want to receive (e.g., kyc.status.changed).
2

Receive your API key

Baanx will generate a unique API key for your webhook. Store it securely — it is used to verify every incoming request.
Never expose your API key in client-side code or public repositories. Store it in a secrets manager or environment variable.
3

Implement signature verification

For every incoming webhook, verify the X-Signature header before processing the event. See the Security guide for full implementation details.
4

Return a 2xx response

Respond with any 2xx HTTP status code within 30 seconds to acknowledge receipt. Process the event asynchronously to avoid timeouts.

​
How It Works

Baanx Platform                    Your Endpoint
      │                                  │
      │  1. Event occurs                 │
      │  2. Sign request (HMAC-SHA256)   │
      │  3. POST with headers & body     │
      │ ─────────────────────────────>   │
      │                                  │  4. Verify signature
      │                                  │  5. Process event (async)
      │   6. Return 2xx status           │
      │ <─────────────────────────────   │

​
Webhook Limits

  • Maximum 5 webhook endpoints per tenant
  • Each webhook can subscribe to multiple event types
  • Subscriptions are managed by Baanx — contact your account team to add, update, or remove webhooks
Self-service webhook management via the API is available. See the Webhooks API Reference for details.

​
Next Steps

Event Types & Payloads

Explore available event types and the standard payload structure

Security & Verification

Implement signature verification and replay protection

Delivery & Retries

Understand retry behaviour and how to respond correctly

KYC Events

Full reference for KYC status change payloads and failure codes