Guides
Recevoir des webhooks
Recevez les événements sur votre serveur et vérifiez qu'Abuna les a envoyés.
Les webhooks permettent à votre serveur de réagir quand quelque chose se produit dans votre application, comme une facture payée ou un abonnement résilié. Abuna envoie un POST HTTPS à l'URL de votre webhook, signé avec votre secret de signature, pour que vous puissiez vérifier qu'il vient d'Abuna.
Ajoutez l'URL de votre webhook
Dans le tableau de bord, ouvrez Webhooks et définissez l'URL du webhook. Seul un propriétaire d'équipe peut la modifier, et uniquement depuis le tableau de bord. Une clé secrète ne peut pas envoyer vos webhooks ailleurs.
Le mode Test et le mode Production ont chacun leur URL de webhook et leur secret de signature. Une nouvelle application Test ne reprend pas l'URL de production, pour que les événements Test n'atteignent jamais un serveur destiné à de vrais clients.
L'URL du webhook doit :
- Utiliser
https. - Avoir un hôte, sans nom d'utilisateur ni mot de passe.
- Ne pas pointer vers
localhost, ni vers une adresse privée, de bouclage, link-local ou de NAT opérateur. Cette règle vaut pour chaque requête et chaque redirection, pas seulement pour l'URL enregistrée.
Pour recevoir des événements sur votre propre machine, exposez-la par un tunnel HTTPS public et utilisez cette URL. Le Démarrage rapide donne une commande pour cela.
Choisissez vos événements
L'URL de votre webhook ne reçoit que les types d'événements que vous choisissez. Quand vous l'ajoutez dans le tableau de bord, Recommandés est déjà sélectionné. Pour changer ce choix plus tard, un propriétaire d'équipe ouvre Webhooks, modifie les Événements, puis garde Recommandés ou coche les événements un par un.
Recommandés regroupe les événements que traite une intégration standard :
session.completed,session.expiredsubscription.created,subscription.trial_ending,subscription.paid,subscription.renewed,subscription.past_due,subscription.recovered,subscription.canceled,subscription.updatedinvoice.created,invoice.paid,invoice.payment_failedcustomer.updated,customer.deleted
Ce sur quoi vous pouvez compter :
- Chaque événement est conservé dans la liste d'événements de votre application, que votre URL le reçoive ou non. Voir Rattraper les événements manqués.
- L'événement de test arrive toujours à votre URL, quel que soit votre choix.
- Un nouveau choix s'applique aux événements qui suivent. Les événements survenus avant ne sont pas envoyés.
- Quand Abuna ajoute un type d'événement, votre URL ne le reçoit pas tant que vous ne l'avez pas choisi.
- Une URL de webhook ajoutée avant le 10 octobre 2026 reçoit tous les types d'événements qui existaient à cette date, jusqu'à ce que vous changiez ses événements.
webhook_events sur l'objet application liste les types d'événements que reçoit votre URL. GET/v1/event-types liste tous les types d'événements que vous pouvez choisir, avec recommended sur ceux de Recommandés. Il ne demande aucune clé.
curl https://api.abuna.app/v1/event-types{
"items": [
{ "type": "session.completed", "recommended": true },
{ "type": "session.expired", "recommended": true },
{ "type": "subscription.created", "recommended": true },
{ "type": "subscription.trial_ending", "recommended": true },
{ "type": "subscription.paid", "recommended": true },
{ "type": "subscription.renewed", "recommended": true },
{ "type": "subscription.past_due", "recommended": true },
{ "type": "subscription.recovered", "recommended": true },
{ "type": "subscription.canceled", "recommended": true },
{ "type": "subscription.updated", "recommended": true },
{ "type": "invoice.created", "recommended": true },
{ "type": "invoice.paid", "recommended": true },
{ "type": "invoice.payment_failed", "recommended": true },
{ "type": "customer.updated", "recommended": true },
{ "type": "customer.deleted", "recommended": true },
{ "type": "customer.updates_changed", "recommended": false },
{ "type": "plan_offer.created", "recommended": false },
{ "type": "plan_offer.confirmed", "recommended": false },
{ "type": "plan_offer.canceled", "recommended": false },
{ "type": "plan_offer.expired", "recommended": false },
{ "type": "price_change.scheduled", "recommended": false },
{ "type": "price_change.canceled", "recommended": false },
{ "type": "price_change.applied", "recommended": false }
],
"next_cursor": null
}Obtenez votre secret de signature
Abuna affiche chaque secret de signature une seule fois : à la création de l'application, et quand vous le renouvelez. Un secret Test ressemble à whsec_test_... et un secret de production à whsec_live_.... Conservez-le sur votre serveur, à côté de votre clé secrète.
Ce qu'Abuna envoie
Chaque livraison est un contenu JSON avec ces en-têtes :
X-Abuna-Event: le type d'événement, commeinvoice.paid.X-Abuna-Delivery: l'identifiant de cette livraison. Il reste le même quand une livraison échouée est envoyée de nouveau. Un renvoi en obtient un nouveau.X-Abuna-Environment:testoulive.X-Abuna-Signature: le moment où Abuna a signé la requête, et la signature. Voir Vérifiez la signature.
Le contenu a toujours les cinq mêmes champs. id est l'identifiant de l'événement. data dépend du type. Le mode figure dans le contenu comme dans l'en-tête, car seul le contenu est signé.
{
"created_at": 1794780106,
"data": {
"amount": 5000,
"coupon_id": null,
"credit": 0,
"currency": "XAF",
"discount": 0,
"invoice_id": "OG3ZsOC7",
"invoice_number": "ACME-000001",
"kind": "period",
"metadata": {
"user_id": "42"
},
"paid_at": 1794780106,
"payment": {
"amount": 5000,
"app_id": "qhf83tDc",
"created_at": 1794780106,
"currency": "XAF",
"driver": "sandbox",
"exchange_margin_bps": null,
"exchange_rate": null,
"exchange_rate_at": null,
"fee": 100,
"id": "tGfwt5dd",
"marked_by_api_key_id": null,
"marked_by_user_id": null,
"message": null,
"method_label": "Successful payment (test)",
"net": null,
"note": null,
"original_amount": 5000,
"original_currency": "XAF",
"period_id": "0kYPFwxJ",
"provider": "test",
"provider_reference": "test_ff6aaf0182bd3f1148bd",
"session_id": null,
"status": "succeeded"
},
"period_end": 1797372106,
"period_id": "0kYPFwxJ",
"period_start": 1794780106,
"promotion_code_id": null,
"subscription": {
"activated_at": 1794780106,
"app_id": "qhf83tDc",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": 1794780106,
"current_period_end": 1797372106,
"current_period_start": 1794780106,
"customer_id": "GzeUZeSV",
"discount": null,
"ended_reason": null,
"id": "wTiODxvH",
"manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"status": "active",
"trial_ends_at": null
},
"subscription_id": "wTiODxvH"
},
"environment": "test",
"id": "01M7GKP458FZEMMQQ7VM7J4QK4",
"type": "invoice.paid"
}Vérifiez la signature
X-Abuna-Signature contient des paires séparées par des virgules. t est le moment où Abuna a signé la requête, en secondes Unix. Chaque v1 est un HMAC-SHA256 hexadécimal, calculé avec votre secret de signature, sur t, un point, et le contenu brut : "<t>.<raw body>".
X-Abuna-Signature: t=1727600000,v1=5f2b8c1e9a4d7f3b6e0c8a2d5f9b1e4c7a3d6f0b8e2c5a9d1f4b7e3c6a0d8f2bPour chaque requête :
- Lisez le contenu brut, en octets, avant de l'analyser.
- Séparez l'en-tête sur les virgules, et chaque paire sur le premier
=. Gardeztet chaquev1. - Si
test à plus de 300 secondes avant ou après l'horloge de votre serveur, répondez400. Cela empêche de rejouer une ancienne requête. - Calculez le HMAC-SHA256 de
t, d'un.et du contenu brut avec votre secret de signature, et encodez-le en hexadécimal. - Comparez le résultat avec chaque
v1, avec une comparaison à temps constant. Acceptez la requête si l'un d'eux correspond. - Si aucun ne correspond, répondez
400et ignorez l'événement.
L'en-tête a généralement un seul v1. Pendant qu'un renouvellement du secret est en cours, il en a deux : un fait avec le nouveau secret et un avec l'ancien. En acceptant n'importe quelle correspondance, votre serveur fonctionne quel que soit le secret qu'il détient. Ignorez les paires que vous ne connaissez pas, pour qu'un nouveau schéma de signature ajouté plus tard ne bloque rien.
import crypto from "node:crypto";
import http from "node:http";
// header is "t=1727600000,v1=<hex>", with a second v1 while a secret rotation overlaps.
function verifyAbunaSignature(rawBody, header, secret) {
const pairs = (header ?? "").split(",").map((part) => part.split("="));
const timestamp = pairs.find(([key]) => key === "t")?.[1] ?? "";
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(timestamp + ".").update(rawBody).digest();
return pairs.some(([key, value]) => {
const received = Buffer.from(key === "v1" ? value ?? "" : "", "hex");
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
http
.createServer((req, res) => {
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", async () => {
const rawBody = Buffer.concat(chunks);
if (!verifyAbunaSignature(rawBody, req.headers["x-abuna-signature"], process.env.ABUNA_WEBHOOK_SECRET)) {
res.writeHead(400).end();
return;
}
const event = JSON.parse(rawBody);
// Save the event before you answer, then handle it in the background.
try {
await saveEvent(event);
} catch {
res.writeHead(500).end();
return;
}
res.writeHead(200).end();
});
})
.listen(3000);Obtenez le contenu brut dans votre framework
Dans Express, express.json() remplace le contenu par du JSON analysé. Utilisez express.raw({ type: "application/json" }) sur la route du webhook, pour que req.body soit les octets qu'Abuna a envoyés.
import express from "express";
const app = express();
// express.raw keeps the bytes. Mount it on the webhook route, before any express.json().
app.post("/webhooks/abuna", express.raw({ type: "application/json" }), async (req, res) => {
if (!verifyAbunaSignature(req.body, req.get("X-Abuna-Signature"), process.env.ABUNA_WEBHOOK_SECRET)) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body);
// Save the event before you answer, then handle it in the background.
try {
await saveEvent(event);
} catch {
return res.sendStatus(500);
}
res.sendStatus(200);
});
app.listen(3000);Dans Laravel, $request->getContent() renvoie le contenu brut. Passez-le à la fonction PHP ci-dessus.
<?php
// routes/api.php. API routes have no CSRF check, so Abuna's POST reaches the handler.
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::post('/webhooks/abuna', function (Request $request) {
// getContent() returns the raw body, before Laravel decodes the JSON.
$rawBody = $request->getContent();
if (!verify_abuna_signature($rawBody, $request->header('X-Abuna-Signature', ''), config('services.abuna.webhook_secret'))) {
abort(400);
}
$event = json_decode($rawBody, true);
// Save the event before you answer, then handle it in the background.
save_event($event);
return response()->noContent();
});Répondez avec un 2xx
Une livraison réussit quand votre serveur répond avec un statut 2xx en 10 secondes. Jusqu'à 4 redirections 307 ou 308 sont suivies, et chacune doit respecter les règles d'URL ci-dessus. Toute autre réponse échoue, y compris une redirection 301, 302 ou 303, un délai dépassé ou une erreur de connexion.
Une livraison échouée est envoyée de nouveau pendant environ une journée, jusqu'à 10 tentatives en tout. Si votre serveur est indisponible moins longtemps, vous ne perdez rien. Ensuite, la livraison passe à failed, et vous pouvez la renvoyer.
Pour traiter les événements sans risque :
- Enregistrez d'abord l'événement, par exemple dans votre base de données, puis répondez
2xx. Après un2xx, Abuna n'envoie plus cette livraison. Si l'enregistrement échoue, répondez500, et la livraison reviendra plus tard. Faites le travail long en arrière-plan après avoir répondu, pour rester dans les 10 secondes. - Enregistrez l'
idde chaque événement et ignorez celui que vous avez déjà traité. Le même événement peut arriver plus d'une fois. - Ne comptez pas sur l'ordre. Un événement plus ancien peut arriver après un plus récent. Voir Gérez les événements dans le désordre.
Gérez les événements dans le désordre
Les identifiants d'événement se trient dans l'ordre où les événements ont eu lieu : comparez-les comme de simples chaînes pour savoir lequel est venu en premier. N'utilisez pas created_at : il est en secondes entières, et les événements d'un même changement le partagent souvent. Par exemple, un paiement produit invoice.paid et subscription.recovered ensemble, dans cet ordre. Voir Ordre des événements pour chaque changement.
Chaque événement sur un abonnement porte l'abonnement entier dans data.subscription, tel qu'il est juste après cet événement. Vous n'avez pas besoin de rejouer les événements dans l'ordre pour connaître l'état d'un abonnement :
- Stockez, pour chaque abonnement, l'identifiant du dernier événement que vous lui avez appliqué.
- Quand un événement arrive, comparez son
idavec celui stocké. S'il est plus récent, enregistrezdata.subscriptioncomme état de l'abonnement et stockez le nouvel identifiant. - S'il est plus ancien, un état plus récent est déjà enregistré. Gardez l'état stocké, et faites quand même le travail ponctuel que l'événement demande, comme un reçu.
Donnez accès au client tant que data.subscription.status vaut trialing, active ou past_due, et retirez-le à canceled. Un renouvellement encore impayé à la fin de la période payée reste past_due jusqu'à ce que le client le paie ou que le délai de paiement soit écoulé.
Types d'événement
session.completed: un client a terminé une session.data.typedit laquelle : pourcheckout, le premier paiement est passé ou un essai gratuit a commencé, etdata.subscription_idest le nouvel abonnement.data.metadataest ce que vous avez passé à sa création.session.expired: une session a expiré, ou vous l'avez fait expirer, sans être terminée.subscription.created: un abonnement a démarré, avectrialingpour un essai gratuit oupendingen attente du premier paiement.subscription.paid: le premier paiement est passé. Après un essai gratuit, c'est la première facture. Le début d'un essai envoie seulementsubscription.created: accordez l'accès tant quedata.subscription.statusvauttrialing. Utilisezinvoice.paidpour suivre les paiements encaissés.subscription.trial_ending: l'essai se termine bientôt, selon le délai habituel des rappels de renouvellement. Voir Essais gratuits.subscription.renewed: la période de facturation suivante et sa facture ont été émises, 3 jours avant la fin de la période payée par défaut. La nouvelle période commence à la date de renouvellement.subscription.past_due: la période payée est terminée et le renouvellement est impayé. Un renouvellement payé avant la fin de la période ne l'envoie jamais. Le client garde l'accès jusqu'à la fin de l'abonnement.subscription.recovered: le renouvellement impayé a été payé, et l'abonnement est de nouveauactive. Il arrive aussi quand un paiement reçu après une résiliation pour non-paiement rétablit l'abonnement.subscription.updated: une résiliation à la fin de la période payée a été programmée ou retirée, le prix a changé, une rétrogradation ou une mise à niveau au prochain renouvellement a été programmée ou retirée, ou une mise à niveau en attente de paiement a expiré.data.cancel_atest la date de fin, ounull, etdata.cancel_at_period_endvauttruetant qu'une résiliation est programmée.data.price_idest le prix actuel, etdata.changedit ce qui a changé sur le prix.data.updated_byvautmerchantoucustomer.plan_offer.created,plan_offer.confirmed,plan_offer.canceled,plan_offer.expired: un changement de formule en attente du client a été créé, accepté, retiré ou remplacé, ou a expiré. Une page d'abonnement en crée un, et en envoie le lien au client par e-mail, quand un client déjà abonné choisit un autre prix du même produit.subscription.canceled: l'abonnement a pris fin, y compris à la fin de la période payée.data.reasonvautmerchant,customer,non_paymentoucheckout_expired.invoice.created: une facture a été émise pour une période de facturation.data.kindvautplan_changepour la première période d'une mise à niveau.invoice.paid: une facture a été payée.data.paymentest le paiement, avec ce que le client a payé en FCFA et le taux de change quand la facture était dans une autre devise.invoice.payment_failed: un paiement sur une facture n'est pas passé.data.paymentest le paiement qui a échoué.price_change.scheduled,price_change.canceled,price_change.applied: un nouveau montant pour un prix a été programmé, retiré ou remplacé, ou a pris effet le jour prévu.data.reasonsurprice_change.canceledvautmerchantoureplaced.customer.updated: le nom, l'e-mail, le numéro de téléphone ou les métadonnées d'un client ont changé, ou son premier paiement lui a donné un numéro de téléphone.data.updated_byvautmerchantoucustomer.customer.deleted: vous avez supprimé un client. Il suit l'événementsubscription.canceledde chaque abonnement qui a pris fin.data.deleted_byvautmerchant.customer.updates_changed: le statut Telegram ou WhatsApp d'un client a changé, par exemple quand il l'a activé ou arrêté.data.channelvauttelegramouwhatsapp,data.statusest le statut actuel etdata.previous_statusle précédent.
Les événements d'abonnement, de facture et de proposition de changement de formule portent les métadonnées de l'abonnement. Les événements de session portent les metadata de la session elle-même, pas celles de l'abonnement. Passez des métadonnées à chaque session que vous créez, pour que ses événements identifient votre client. Sans elles, les événements de session portent {}.
Chaque événement est aussi conservé dans la liste d'événements de votre application, même sans URL de webhook ou quand votre URL ne reçoit pas son type. Voir Événements pour le data de chaque type.
Chaque événement dont le data a un subscription_id a aussi data.subscription, l'objet abonnement complet tel qu'il est juste après l'événement.
Envoyez un événement de test
Pour vérifier l'URL de votre webhook, cliquez sur Envoyer un événement de test dans le tableau de bord, ou appelez POST/v1/apps/{appID}/webhooks/test. Abuna envoie tout de suite un événement ping signé et vous dit comment votre serveur a répondu, quels que soient les événements choisis. Il part une seule fois, et il n'est enregistré ni comme événement ni comme livraison.
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/webhooks/test \
-H "Authorization: Bearer sk_test_..."{
"delivered": true,
"response_status": 200,
"error": null
}delivered vaut true quand votre serveur a répondu 2xx. Sans réponse, response_status vaut null et error dit pourquoi. Vous pouvez envoyer 10 événements de test par minute. Sans URL de webhook, l'appel renvoie 422 avec le code webhook_url_missing.
{
"id": "01J9ZQ8E1F2G3H4J5K6M7N8P9Q",
"type": "ping",
"environment": "test",
"created_at": 1727600000,
"data": {
"message": "A test event sent from the Abuna dashboard."
}
}Renvoyez les événements échoués
Une fois votre serveur réparé, listez les livraisons échouées avec GET/v1/apps/{appID}/webhooks?status=failed, puis renvoyez chacune avec POST/v1/apps/{appID}/webhooks/{id}/redeliver. Un renvoi envoie de nouveau le même contenu, comme une nouvelle livraison, à l'URL actuelle de votre webhook. Il est signé avec votre secret actuel et envoyé de nouveau en cas d'échec, comme toute livraison.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/webhooks?status=failed&limit=100" \
-H "Authorization: Bearer sk_test_..."
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/webhooks/R3vH6sLd/redeliver \
-H "Authorization: Bearer sk_test_..."Voir Livraisons de webhooks pour les champs de chaque livraison. Pour trouver les événements que votre serveur n'a jamais traités, quel que soit leur statut de livraison, parcourez la liste d'événements. Voir Rattraper les événements manqués.
Renouvelez le secret de signature
Si votre secret de signature fuite, un propriétaire d'équipe peut cliquer sur Renouveler le secret sur la page Webhooks. Une clé secrète ne peut pas le renouveler. Abuna affiche le nouveau secret une seule fois et signe avec lui tout de suite.
Pendant les 24 heures suivantes, X-Abuna-Signature porte un second v1, signé avec l'ancien secret. Mettez le nouveau secret sur votre serveur dans ce délai. Si vous renouvelez encore dans les 24 heures, le secret que vous venez de remplacer devient l'ancien, et celui d'avant cesse de fonctionner.