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

# Webhook Request Format

> Understanding the request format that Kairos Afrika sends to your webhook endpoint

# Webhook Request Format

When a user interacts with your USSD application, Kairos Afrika will send a POST request to your configured webhook endpoint. Your endpoint should be prepared to receive and process these requests.

## Request Details

* **Method**: `POST`
* **Content-Type**: `application/json`
* **Endpoint**: Your provided webhook URL (e.g., `https://example.com/ussd`)

<Warning>
  The endpoint URL `https://example.com/ussd` is just an example. You need to provide your actual webhook endpoint URL to Kairos Afrika.
</Warning>

## Request Body Structure

The request body contains the following fields:

| Field         | Type   | Description                                    | Example                |
| ------------- | ------ | ---------------------------------------------- | ---------------------- |
| `msisdn`      | string | The user's phone number                        | `"233559400612"`       |
| `sessionId`   | string | Unique identifier for the USSD session         | `"171632898024603649"` |
| `messageType` | string | Type of USSD message (usually "0" for request) | `"0"`                  |
| `ussdString`  | string | The USSD code or user input                    | `"*889*90#"`           |

## Example Request

Here's an example of what Kairos Afrika will send to your webhook:

```json theme={null}
{
    "msisdn": "233559400612",
    "sessionId": "171632898024603649",
    "messageType": "0",
    "ussdString": "*889*90#"
}
```

## Field Descriptions

### `msisdn`

The mobile subscriber number (phone number) of the user initiating the USSD session. This is typically in international format without the `+` prefix.

### `sessionId`

A unique identifier for this USSD session. Use this to track the conversation flow and maintain state between requests from the same user.

### `messageType`

Indicates the type of USSD message:

* `"0"` - Initial request or user input
* Other values may be used for different message types

### `ussdString`

Contains either:

* The initial USSD code dialed by the user (e.g., `*889*90#`)
* User input in response to your menu prompts (e.g., `1`, `2`, etc.)

## Processing the Request

Your webhook endpoint should:

1. **Validate the request** - Ensure all required fields are present
2. **Process the session** - Use the `sessionId` to maintain conversation state
3. **Generate appropriate response** - Based on the `ussdString` and current session state
4. **Return the response** - In the expected format (see [Webhook Response Format](./webhook-response))

## Next Steps

Learn how to structure your response in the [Webhook Response Format](./webhook-response) documentation.