Webhooks d'abonnement
Les événements clients, abonnements et factures, leur contenu et la façon de les traiter.
Les événements d'abonnement passent par les mêmes endpoints webhook que les paiements. Abonnez un endpoint aux événements voulus depuis la page Webhooks du dashboard, ou par l'API de gestion. La signature se vérifie de la même façon : voir vérification de signature.
Un endpoint reçoit les événements de l'environnement dans lequel il a été créé : créez-en un en sandbox et un en live.
Forme du payload
{
"id": "01K92B7Q4X8V3N6M1C5D9F2H0J",
"event": "subscription.past_due",
"timestamp": "2026-11-01T23:15:02.481000Z",
"data": {
"id": "01k6f3m8n2p4q6r8s0t2v4w6x8",
"object": "subscription",
"status": "past_due",
"customer": "01k6f3k1a3b5c7d9e1f3g5h7j9",
"price": { "id": "01k6dz8m0n2p4q6r8s0t2v4w6x", "object": "price", "amount": 15000, "currency": "XAF", "interval": "month", "grace_days": 7 },
"product_name": "Salle de sport, accès illimité",
"payment_phone": "+237670000001",
"current_period_end": "2026-10-31T23:00:00.000000Z",
"next_due_at": "2026-10-31T23:00:00.000000Z",
"has_access": true,
"access_until": "2026-11-07T23:00:00.000000Z",
"metadata": { "crm_id": "abc" },
"previous_attributes": { "status": "active" },
"context": { "invoice_id": "01k8b4x0y2z4a6b8c0d2e4f6g8", "due_at": "2026-10-31T23:00:00.000000Z" }
}
}dataest l'objet concerné, tel que renvoyé par l'API : abonnement (aveccustomeren identifiant), facture (aveccustomeretpayments), client (avec sescontacts) ou contact. L'extrait ci-dessus est abrégé.data.previous_attributesdonne l'ancienne valeur des champs qui ont changé. Absent quand rien n'a changé.data.contextdonne le contexte de l'événement, quand il y en a un.ididentifie la livraison : une nouvelle tentative garde le mêmeid. Il est aussi envoyé dans l'en-têteX-Webhook-Id, et le nom de l'événement dansX-Webhook-Event.
Livraison
- Un événement est envoyé une fois la modification enregistrée. Une opération annulée n'envoie rien.
- Votre endpoint doit répondre
2xxen moins de 3 secondes. Sinon, la livraison est retentée après 10 secondes, puis après 100 secondes. Après 3 échecs, elle est abandonnée. - L'ordre d'arrivée n'est pas garanti. Quand un même traitement émet plusieurs événements (
invoice.paidpuissubscription.activated), ils partent dans cet ordre, mais peuvent arriver dans un autre.
Traitez donc chaque événement de façon idempotente, en vous basant sur id. Pour un état fiable, relisez l'objet par l'API plutôt que d'appliquer les événements les uns après les autres.
Événements
Abonnements
| Événement | Quand | context |
|---|---|---|
subscription.created | Abonnement créé, en incomplete ou trialing (active pour un import) | source, import_id pour un import |
subscription.activated | Premier paiement reçu : incomplete ou trialing → active | invoice_id |
subscription.renewed | Renouvellement payé, nouvelle période ouverte (depuis active ou past_due) | invoice_id |
subscription.trial_will_end | L'essai se termine dans 3 jours. Envoyé une fois. | trial_ends_at |
subscription.past_due | Échéance dépassée d'un jour, ou essai terminé sans paiement. L'accès est maintenu. | invoice_id, due_at |
subscription.suspended | Délai de grâce écoulé, l'accès est coupé | invoice_id, due_at |
subscription.reactivated | Paiement reçu pendant la suspension, l'accès revient | invoice_id |
subscription.cancellation_scheduled | Résiliation programmée à la fin de la période | reason, cancel_at |
subscription.cancellation_withdrawn | Résiliation programmée annulée | |
subscription.cancelled | Abonnement terminé. La cause est dans cancellation_reason : customer_request, merchant_request, unpaid ou incomplete_expired. | reason, invoice_id pour un impayé |
subscription.completed | Dernière période payée d'une formule à durée fixe terminée | |
subscription.updated | Numéro de paiement, bénéficiaire ou metadata modifiés ; échéance reportée ; numéro de paiement changé par un paiement ; accès ouvert à la date de début d'un abonnement payé ou en essai avant elle | reason: "due_date_shifted" et invoice_id, invoice_id, ou reason: "started" |
Factures
| Événement | Quand | context |
|---|---|---|
invoice.created | Facture émise, ou facture de remplacement | subscription_id, replaces_invoice_id |
invoice.paid | Facture soldée | source (push, page, manual, credit), payin_id, track_id, invoice_payment_id, amount, credited |
invoice.payment_failed | Un paiement mobile money sur la facture a échoué ou expiré | payin_id, track_id, reason, source |
invoice.voided | Facture annulée, par vous ou à la fin de l'abonnement | reason (merchant_request ou subscription_cancelled), replaced_by, cancellation_reason |
invoice.uncollectible | Facture restée impayée jusqu'à la fin de l'abonnement, envoyée avec subscription.cancelled | |
invoice.updated | Échéance reportée, crédit appliqué en partie, ou paiement en double passé en crédit | reason (due_date_shifted, duplicate_payment), détails du paiement |
Clients
| Événement | Quand | context |
|---|---|---|
customer.created | Client créé | source : api, import ou signup_link |
customer.updated | Client modifié, contact ajouté ou supprimé, contact préféré changé ou canal réactivé depuis le portail | contact_id, change (contact_added, contact_removed, preferred_contact, contact_opted_in), channel, source: "portal" depuis le portail |
customer.contact_verified | Contact confirmé par code, par un lien d'abonnement, ou joint pour la première fois | source : otp, signup_link ou delivery, channel |
customer.contact_unreachable | Contact devenu injoignable | reason, consecutive_failures, error_code, channel |
customer.contact_opted_out | Le client ne veut plus de messages sur ce canal | source : whatsapp ou portal, channel |
« Vérifié » ou « joignable »
customer.contact_verified avec context.source: "delivery" signifie qu'un message a été livré : le contact passe reachable, mais son champ verified reste false. Seuls un code à usage unique ou un lien d'abonnement rendent un contact verified.
Exemple : facture payée
{
"id": "01K93F0A2B4C6D8E0F2G4H6J8K",
"event": "invoice.paid",
"timestamp": "2026-11-03T10:12:43.907000Z",
"data": {
"id": "01k8b4x0y2z4a6b8c0d2e4f6g8",
"object": "invoice",
"number": "INV-000002",
"status": "paid",
"customer_id": "01k6f3k1a3b5c7d9e1f3g5h7j9",
"customer": { "id": "01k6f3k1a3b5c7d9e1f3g5h7j9", "name": "Awa Ngono" },
"subscription_id": "01k6f3m8n2p4q6r8s0t2v4w6x8",
"amount_due": 15000,
"amount_paid": 15000,
"amount_remaining": 0,
"currency": "XAF",
"paid_at": "2026-11-03T10:12:41.000000Z",
"payments": [
{
"id": "01k8c2n8x6w4v2t0s8r6q4p2m0",
"object": "invoice_payment",
"source": "push",
"amount": 15000,
"payin_id": "01k8c2m4d6e8f0g2h4j6k8m0n2",
"paid_at": "2026-11-03T10:12:41.000000Z",
"note": null
}
],
"previous_attributes": { "status": "open", "amount_paid": 0, "amount_remaining": 15000, "paid_at": null },
"context": {
"source": "push",
"payin_id": "01k8c2m4d6e8f0g2h4j6k8m0n2",
"track_id": "PX-01k8c2m4d6e8f0g2h4j6k8m0n2",
"invoice_payment_id": "01k8c2n8x6w4v2t0s8r6q4p2m0",
"amount": 15000,
"credited": 0
}
}
}Il est suivi de subscription.renewed (ici, l'abonnement était past_due). credited donne la part du paiement passée en crédit pour le client, en cas de trop-perçu.
How is this guide?
Last updated on