> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time event notifications from the Baanx platform

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.

<CardGroup cols={2}>
  <Card title="Secure Delivery" icon="shield-halved">
    HMAC-SHA256 signed requests let you verify every delivery is genuinely from Baanx
  </Card>

  <Card title="Replay Protection" icon="clock">
    Timestamp-based validation prevents replayed or stale requests from being accepted
  </Card>

  <Card title="Automatic Retries" icon="rotate">
    Exponential backoff retries ensure delivery even through transient failures
  </Card>

  <Card title="Idempotent Events" icon="fingerprint">
    Every event has a unique `event_id` so your endpoint can safely handle duplicates
  </Card>
</CardGroup>

## 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

<Warning>
  Only HTTPS endpoints are accepted. Plain HTTP URLs will be rejected.
</Warning>

## Quick Start

<Steps>
  <Step title="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`).
  </Step>

  <Step title="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.

    <Warning>
      Never expose your API key in client-side code or public repositories. Store it in a secrets manager or environment variable.
    </Warning>
  </Step>

  <Step title="Implement signature verification">
    For every incoming webhook, verify the `X-Signature` header before processing the event. See the [Security guide](/guides/webhooks/security) for full implementation details.
  </Step>

  <Step title="Return a 2xx response">
    Respond with any `2xx` HTTP status code within **30 seconds** to acknowledge receipt. Process the event asynchronously to avoid timeouts.
  </Step>
</Steps>

## 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

<Note>
  Self-service webhook management via the API is available. See the [Webhooks API Reference](/api-reference/webhooks/list-webhooks) for details.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Event Types & Payloads" icon="list" href="/guides/webhooks/events">
    Explore available event types and the standard payload structure
  </Card>

  <Card title="Security & Verification" icon="lock" href="/guides/webhooks/security">
    Implement signature verification and replay protection
  </Card>

  <Card title="Delivery & Retries" icon="truck-fast" href="/guides/webhooks/delivery">
    Understand retry behaviour and how to respond correctly
  </Card>

  <Card title="KYC Events" icon="id-card" href="/guides/webhooks/kyc-events">
    Full reference for KYC status change payloads and failure codes
  </Card>
</CardGroup>