Webhooks

Working with webhooks

Djamo uses webhooks to notify your application about events related to your API requests so it can react accordingly. For example: we can notify your application when a transaction has been completed.

Working with webhooks is very simple:

1. Identify the events that you want to monitor.
2. Create webhook endpoints (URLs) on your servers to receive the events payloads.
3. Register those URLs on the Djamo API.
4. When those events occur, Djamo sends to the URLs a HTTP POST request with a payload.
5. Verify that Djamo is indeed sending you the payload by validation the header x-djamo-hmac-sha256 inside of the HTTP request.
6. Respond to the HTTP POST request with an HTTP status code 2xx to indicate that the event was received successfully.

Currently, you can listen to the following events :

Event	Description
transactions/started	Sent when a request for a transaction has been received and queued.
transactions/completed	Sent when the transaction has been successfuly executed.
transactions/failed	Sent when we failed to execute the transaction for some reason.

Creating a webhook

POST /v1/webhooks

Parameters

Parameter	Type	Description
topic	String	The event that you want to be notified about
url	String	The URL of the endpoint that will receive the event payload

Example

RequestResponse

curl \
-X POST \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-type: application/json' \
-d '{
    "topic": "transactions/started",
    "url": "https://myapp.com/webhooks/djamo_transfers"
}' \
<BASE_URL>/v1/webhooks

{
"id": "2cdc8ab1-6d50-49cc-ba14-54e4ac7ec231",
"createdAt": "2020-11-24T17:43:15.970Z",
"updatedAt": "2020-11-24T17:43:15.970Z",
"topic": "transaction/started",
"url": "https://myapp.com/webhooks/djamo_transfers"
}

Retrieving details about a webhook

GET /v1/webhooks/<id>

Example

RequestResponse

curl \
-X GET \
-H 'Authorization: Bearer <API_KEY>' \
<BASE_URL>/v1/webhooks/2cdc8ab1-6d50-49cc-ba14-54e4ac7ec231

{
"id": "2cdc8ab1-6d50-49cc-ba14-54e4ac7ec231",
"createdAt": "2020-11-24T17:43:15.970Z",
"updatedAt": "2020-11-24T17:43:15.970Z",
"topic": "transaction/started",
"url": "https://myapp.com/webhooks/djamo_transfers"
}

Retrieving the list of your webhooks

GET /v1/webhooks

Example

RequestResponse

curl \
-X GET \
-H 'Authorization: Bearer <API_KEY>' \
<BASE_URL>/v1/webhooks

{
    "count": 1,
    "limit": 15,
    "cursor": {
        "prev": null,
        "next": "bmV4dF9fXzE2Nzg4OTg4MzA2MjA="
    },
    "data": [
        {
            "id": "2cdc8ab1-6d50-49cc-ba14-54e4ac7ec231",
            "createdAt": "2020-11-24T17:43:15.970Z",
            "updatedAt": "2020-11-24T17:43:15.970Z",
            "topic": "transaction/started",
            "url": "https://myapp.com/webhooks/djamo_transfers"
        },

        {
            "id": "fdfd3ee0-e602-4957-afdd-e3c9e0413af4",
            "createdAt": "2020-11-24T17:43:15.970Z",
            "updatedAt": "2020-11-24T17:43:15.970Z",
            "topic": "transaction/completed",
            "url": "https://myapp.com/webhooks/djamo_transfers"
        }
    ]
}

Deleting a webhook

DELETE /v1/webhooks/<id>

Example

RequestResponse

curl \
-X DELETE \
-H 'Authorization: Bearer <API_KEY>' \
<BASE_URL>/v1/webhooks/<id>

This will return an empty response with an HTTP code 204.

Verifying payloads from Djamo

Djamo will sign the webhook events it sends to your endpoints by including a signature in each event’s x-djamo-hmac-sha256 HTTP header. This allows you to verify that the events were sent by Djamo, not by a third party. You can verify signatures using the method below.

1. Retrieve the SECRET_KEY sent to you along with your API_KEY.
2. Compute an HMAC with the SHA256 hash function. Use the SECRET_KEY as the key, and use the event's payload body string as the message.
3. Compare the obtained signature to the one in the x-djamo-hmac-sha256 HTTP header. If they are the same then you can assume this payload comes from Djamo. Otherwise No.

Parsing the payload data

Djamo will include the event topic in the event's HTTP header x-djamo-webhook-topic. Djamo will also include information to process the event in the event's payload body.

Below is an exemple of such payload body.

{
  "data": {
    "id": "17750afb-e314-445f-868f-7c75468daac9",
    "status": "completed",
    "amount": 50,
    "msisdn": "+2259800207673",
    "description": "Premier test de bulk",
    "type": "transfer",
    "reference": "89bbf385-da31-4818-9921-542accc77c2d",
    "fee": 0.5,
    "totalAmount": 50.5,
    "failureReason": null,
    "batchId": "561958dc-3575-4eef-9e3f-578169b0500d",
    "createdAt": "2023-03-23T15:39:42.775Z",
    "updatedAt": "2023-03-23T15:40:12.879Z"
  },
  "topic": "transactions/completed"
}