Webhooks

Webhooks are an important part of your payment integration. They allow Swahilies Pay notify you about events that happen on your account, such as a successful payment or a failed transaction.

A webhook URL is an endpoint on your server where you can receive notifications about such events. When an event occurs, we'll make a POST request to that endpoint, with a JSON body containing the details about the event.

The response body on the callback contains the following.

Code	200 for success and 300 for error
order_id	your order_id submitted when initiating check out process
reference_id	the reference of the transaction to swahilies
amount	the order amount

Sample of response body

Python

{
     "code":200,
     "transaction_details":
     {
       "order_id":order.client_order_id,
       "reference_id":order.order_id,
    }
}

Verifying webhook

For security purpose is very important user verify the webhook callback

The header of the response :

header-key	value
Digest	the signed based64 encoded hmac signature using the api_secret

The signed signature consist of the combination of the timestamp, server IPand the api_key

This will be enable user to verify the request , after decrypting compare the timestamp, the server IP address and the api_key

Example

1. Get the timestamp from the main response object.
2. Fetch the IP the callback is coming from
3. Together with your api key combine to make a string of key = value, as below
4. Then using your secret key sign the the created string using hmac256.
5. Encode the signature with base64 and compare it to the Digest coming in the request heade

Python

fordigest = {
    "timestamp": current_date,
    "server_ip": "oo.00.00.189",
    "api_key": "your_api_key"
}
toDigest = ""
    for key in fordigest.keys():
        toDigest += "&" + key + "=" + array[key]
    # return toDigest
 base64.b64encode(
        hmac.digest(api_secret.encode(), toDigest.encode(), 'sha256')).decode()