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

# Webhooks Overview

> Learn how to configure a Kulmi Pay webhook endpoint to receive instant notifications whenever a payment, Send Money request, or wallet transfer changes state.

Webhooks let KulmiPay push notifications to your server when supported account events happen. Instead of polling for every payment or transfer, you register an HTTPS endpoint and KulmiPay sends a JSON `POST` whenever a subscribed event changes state.

## Supported events

| Event flag              | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| `collection_event`      | Payment invoice state changes for M-Pesa and PesaLink collections. |
| `send_money_event`      | Send Money payment file state changes.                             |
| `reversal_event`        | Chargeback and reversal state changes.                             |
| `wallet_transfer_event` | Wallet intra-transfer events.                                      |

## Requirements

* Your endpoint must accept `POST` requests.
* Your endpoint must use HTTPS.
* Your endpoint should respond with HTTP `200` or `201` quickly.
* Your handler should be idempotent because events can be retried or replayed.
* Use the `challenge` value in the payload to verify the request came from KulmiPay.

## Payload shape

KulmiPay posts the event resource directly to your endpoint and adds the configured `challenge` value to the JSON body. The webhook event log stores the event `topic`, but the merchant endpoint receives the event payload itself.

```json theme={null}
{
  "invoice_id": "GQ7KZ2XPNM",
  "state": "COMPLETE",
  "provider": "M-PESA",
  "value": "1500.00",
  "currency": "KES",
  "challenge": "your-configured-secret"
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="How to Setup Webhook" icon="gear" href="/webhooks/setup">
    Configure your endpoint and verify incoming events.
  </Card>

  <Card title="Payment Collection Events" icon="arrow-down-to-line" href="/webhooks/payment-collection-events">
    Handle M-Pesa and PesaLink collection updates.
  </Card>

  <Card title="Send Money Events" icon="arrow-up-from-line" href="/webhooks/send-money-events">
    Handle Send Money file status changes.
  </Card>

  <Card title="Wallet Intra-Transfer Events" icon="arrows-right-left" href="/webhooks/wallet-intra-transfer-events">
    Handle wallet transfer updates.
  </Card>
</CardGroup>