Logo GenukaGenuka Pay
Référence APIAbonnements

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" }
  }
}
  • data est l'objet concerné, tel que renvoyé par l'API : abonnement (avec customer en identifiant), facture (avec customer et payments), client (avec ses contacts) ou contact. L'extrait ci-dessus est abrégé.
  • data.previous_attributes donne l'ancienne valeur des champs qui ont changé. Absent quand rien n'a changé.
  • data.context donne le contexte de l'événement, quand il y en a un.
  • id identifie la livraison : une nouvelle tentative garde le même id. Il est aussi envoyé dans l'en-tête X-Webhook-Id, et le nom de l'événement dans X-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 2xx en 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.paid puis subscription.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énementQuandcontext
subscription.createdAbonnement créé, en incomplete ou trialing (active pour un import)source, import_id pour un import
subscription.activatedPremier paiement reçu : incomplete ou trialing → activeinvoice_id
subscription.renewedRenouvellement payé, nouvelle période ouverte (depuis active ou past_due)invoice_id
subscription.trial_will_endL'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.suspendedDélai de grâce écoulé, l'accès est coupéinvoice_id, due_at
subscription.reactivatedPaiement reçu pendant la suspension, l'accès revientinvoice_id
subscription.cancellation_scheduledRésiliation programmée à la fin de la périodereason, cancel_at
subscription.cancellation_withdrawnRésiliation programmée annulée
subscription.cancelledAbonnement terminé. La cause est dans cancellation_reason : customer_request, merchant_request, unpaid ou incomplete_expired.reason, invoice_id pour un impayé
subscription.completedDernière période payée d'une formule à durée fixe terminée
subscription.updatedNumé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 ellereason: "due_date_shifted" et invoice_id, invoice_id, ou reason: "started"

Factures

ÉvénementQuandcontext
invoice.createdFacture émise, ou facture de remplacementsubscription_id, replaces_invoice_id
invoice.paidFacture soldéesource (push, page, manual, credit), payin_id, track_id, invoice_payment_id, amount, credited
invoice.payment_failedUn paiement mobile money sur la facture a échoué ou expirépayin_id, track_id, reason, source
invoice.voidedFacture annulée, par vous ou à la fin de l'abonnementreason (merchant_request ou subscription_cancelled), replaced_by, cancellation_reason
invoice.uncollectibleFacture 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éditreason (due_date_shifted, duplicate_payment), détails du paiement

Clients

ÉvénementQuandcontext
customer.createdClient créésource : api, import ou signup_link
customer.updatedClient modifié, contact ajouté ou supprimé, contact préféré changé ou canal réactivé depuis le portailcontact_id, change (contact_added, contact_removed, preferred_contact, contact_opted_in), channel, source: "portal" depuis le portail
customer.contact_verifiedContact confirmé par code, par un lien d'abonnement, ou joint pour la première foissource : otp, signup_link ou delivery, channel
customer.contact_unreachableContact devenu injoignablereason, consecutive_failures, error_code, channel
customer.contact_opted_outLe client ne veut plus de messages sur ce canalsource : 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