Aller au contenu

Events

Utilisation des webhooks

Djamo utilise les webhooks pour notifier votre application des événements liés à vos requêtes API afin qu'elle puisse réagir en conséquence. Par exemple : nous pouvons notifier votre application lorsqu'une transaction a été complétée.

Utiliser les webhooks est très simple :

  1. Identifiez les événements que vous souhaitez surveiller.
  2. Créez des endpoints webhook (URLs) sur vos serveurs pour recevoir les payloads des événements.
  3. Enregistrez ces URLs sur l'API Djamo.
  4. Lorsque ces événements se produisent, Djamo envoie aux URLs une requête HTTP POST avec un payload.
  5. Vérifiez que c'est bien Djamo qui vous envoie le payload en vérifiant l'en-tête x-djamo-hmac-sha256 dans la requête HTTP.
  6. Répondez à la requête HTTP POST avec un code de statut HTTP 2xx pour indiquer que l'événement a bien été reçu.

Actuellement, vous pouvez écouter les événements suivants :

Événement Description
transactions/started Envoyé quand une demande de transaction a été reçue et mise en file d'attente.
transactions/completed Envoyé quand la transaction a été exécutée avec succès.
transactions/failed Envoyé quand nous n'avons pas réussi à exécuter la transaction.
charge/events Envoyé quand le statut d'une charge est mis à jour.

Créer un webhook

POST /v1/webhooks

Paramètres

Paramètre Type Description
topic String L'événement pour lequel vous souhaitez être notifié
url String L'URL de l'endpoint qui recevra le payload de l'événement 
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"
}

Récupérer les détails d'un 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"
}

Récupérer la liste de vos 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"
            }
        ]
    }

Supprimer un webhook

DELETE /v1/webhooks/:id

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

Cela retournera une réponse vide avec un code HTTP 204.

Vérifier les payloads de Djamo

Djamo signera les événements webhook qu'il envoie à vos endpoints en incluant une signature dans l'en-tête HTTP x-djamo-hmac-sha256 de chaque événement. Cela vous permet de vérifier que les événements ont bien été envoyés par Djamo et non par un tiers. Vous pouvez vérifier les signatures en utilisant la méthode ci-dessous.

  1. Récupérez le SECRET_KEY qui vous a été transmis avec votre ACCESS_TOKEN.
  2. Calculez un HMAC avec la fonction de hachage SHA256. Utilisez le SECRET_KEY comme clé, et la chaîne du corps du payload de l'événement comme message.
  3. Encodez le HMAC résultant en Base64.
  4. Comparez cette signature à la valeur dans l'en-tête x-djamo-hmac-sha256. Si elles correspondent, le payload est authentique ; sinon, rejetez la requête.

Analyser les données du payload

Voici des exemples de payload pour chaque type d'événement.

{
  "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"
}