Skip to content

Events

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 verifiying 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.
charge/events Sent when the status of a charge is updated

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

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

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

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 ACCESS_TOKEN.
  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. Base64-encode the resulting HMAC.
  4. Compare that signature to the value in the x-djamo-hmac-sha256 header. If they match, the payload is authentic; otherwise, reject the request.

Parsing the payload data

Here are examples of payload for each type of events.

{
  "data": {
    "id": "6cea81df-49fd-4588-a5a9-91363ccd5d1b",
    "externalId": "27",
    "description": "Paiement effectué chez Ruth Corp",
    "currency": "XOF",
    "amount": 100,
    "due": 0,
    "status": "paid",
    "droppedReason": null,
    "paid": 100,
    "refunded": 0,
    "attempts": 1,
    "metadata": {}
  },
  "topic": "charge/events"
}

{
  "data": {
    "id": "txn_ef1d55f2-1e15-45b0-8f7d-0c1872005492",
    "status": "pending",
    "amount": 500,
    "msisdn": "2250768101008",
    "description": "Test transfert",
    "type": "transfer",
    "reference": "12",
    "fee": 0,
    "totalAmount": 500,
    "failureReason": null,
    "createdAt": "2026-02-26T10:05:14.833Z",
    "updatedAt": "2026-02-26T10:05:14.833Z"
  },
  "topic": "transactions/started"
}

{
  "data": {
    "id": "txn_ef1d55f2-1e15-45b0-8f7d-0c1872005492",
    "status": "completed",
    "amount": 500,
    "msisdn": "2250768101008",
    "description": "Test transfert",
    "type": "transfer",
    "reference": "12",
    "fee": 0,
    "totalAmount": 500,
    "batchId": "bat_c74b9bf9-9e66-46cd-84af-bd1b45d5be19",
    "failureReason": null,
    "createdAt": "2026-02-26T10:05:14.833Z",
    "updatedAt": "2026-02-26T10:05:16.569Z"
  },
  "topic": "transactions/completed"
}

{
  "data": {
    "id": "txn_ba559505-90da-4755-9433-b90e2ccdd0eb",
    "status": "failed",
    "amount": 500,
    "msisdn": "2251212121205",
    "description": "Test transfert",
    "type": "transfer",
    "reference": "13",
    "fee": 0,
    "totalAmount": 500,
    "batchId": "bat_43b65063-2dc8-4094-a0e5-cc86395ba195",
    "failureReason": "echec de la transaction",
    "createdAt": "2026-02-26T10:42:44.465Z",
    "updatedAt": "2026-02-26T10:42:44.465Z"
  },
  "topic": "transactions/failed"
}