Skip to main content

​
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)
The endpoint URL https://example.com/ussd is just an example. You need to provide your actual webhook endpoint URL to Kairos Afrika.

​
Request Body Structure

The request body contains the following fields:
FieldTypeDescriptionExample
msisdnstringThe user’s phone number"233559400612"
sessionIdstringUnique identifier for the USSD session"171632898024603649"
messageTypestringType of USSD message (usually “0” for request)"0"
ussdStringstringThe USSD code or user input"*889*90#"

​
Example Request

Here’s an example of what Kairos Afrika will send to your webhook: 
{
    "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)

​
Next Steps

Learn how to structure your response in the Webhook Response Format documentation.