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

# USSD Webhook Integration

> Learn how to integrate with Kairos Afrika's USSD service through webhooks.

# USSD Webhook Integration

Kairos Afrika's USSD service works as a webhook-based integration. **We don't provide endpoints for you to call**. Instead, you provide us with your webhook endpoint, and we push USSD session data to your endpoint when users interact with your USSD application.

## How It Works

1. **You provide the endpoint**: You give us your webhook URL (e.g., `https://yourapp.com/ussd`)
2. **We push requests**: When users dial your USSD code, we send the session data to your endpoint
3. **You respond**: Your endpoint processes the request and returns the appropriate response
4. **We handle the display**: We show your response to the user on their mobile device

## Integration Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant KairosAfrika as Kairos Afrika
    participant YourApp as Your Webhook Endpoint

    User->>KairosAfrika: Dials USSD code (*889*90#)
    KairosAfrika->>YourApp: POST /your-webhook-url
    Note over YourApp: Process request & generate response
    YourApp->>KairosAfrika: Return USSD response
    KairosAfrika->>User: Display response on mobile
```

## Example Use Cases

* Balance checks and account inquiries
* Airtime top-up and bill payments
* Service subscriptions and activations
* Customer support menus
* Mobile banking operations

## Webhook Documentation

* [Webhook Request Format](./endpoint/webhook-request) - What we send to your endpoint
* [Webhook Response Format](./endpoint/webhook-response) - What you should return

***

<Note>
  The endpoint URL `https://example.com/ussd` used in examples is just a placeholder. Replace it with your actual webhook endpoint URL.
</Note>