Subscription webhooks
Customer, subscription and invoice events, what they contain and how to handle them.
Subscription events go through the same webhook endpoints as payments. Subscribe an endpoint to the events you want from the Webhooks page in the dashboard, or through the management API. The signature is verified the same way: see signature verification.
An endpoint receives the events of the environment it was created in: create one in sandbox and one in live.
Payload shape
{
"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": "Gym, unlimited access",
"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" }
}
}datais the object concerned, as returned by the API: subscription (withcustomeras an ID), invoice (withcustomerandpayments), customer (with itscontacts) or contact. The excerpt above is abridged.data.previous_attributesgives the previous value of the fields that changed. Absent when nothing changed.data.contextgives the context of the event, when there is one.ididentifies the delivery: a retry keeps the sameid. It is also sent in theX-Webhook-Idheader, and the event name inX-Webhook-Event.
Delivery
- An event is sent once the change has been saved. An operation that is rolled back sends nothing.
- Your endpoint must respond with a
2xxwithin 3 seconds. Otherwise, delivery is retried after 10 seconds, then after 100 seconds. After 3 failures, it is abandoned. - Arrival order is not guaranteed. When a single operation emits several events (
invoice.paidthensubscription.activated), they are sent in that order, but may arrive in a different one.
So handle each event idempotently, based on id. For reliable state, fetch the object again from the API rather than applying events one after another.
Events
Subscriptions
| Event | When | context |
|---|---|---|
subscription.created | Subscription created, as incomplete or trialing (active for an import) | source, import_id for an import |
subscription.activated | First payment received: incomplete or trialing → active | invoice_id |
subscription.renewed | Renewal paid, new period opened (from active or past_due) | invoice_id |
subscription.trial_will_end | The trial ends in 3 days. Sent once. | trial_ends_at |
subscription.past_due | Due date passed by one day, or trial ended without payment. Access is kept. | invoice_id, due_at |
subscription.suspended | Grace period over, access is cut off | invoice_id, due_at |
subscription.reactivated | Payment received during suspension, access is restored | invoice_id |
subscription.cancellation_scheduled | Cancellation scheduled for the end of the period | reason, cancel_at |
subscription.cancellation_withdrawn | Scheduled cancellation withdrawn | |
subscription.cancelled | Subscription ended. The cause is in cancellation_reason: customer_request, merchant_request, unpaid or incomplete_expired. | reason, invoice_id for non-payment |
subscription.completed | Last paid period of a fixed-term price has ended | |
subscription.updated | Payment number, beneficiary or metadata changed; due date postponed; payment number changed by a payment; access opened on the start date of a subscription paid or on trial ahead of that date | reason: "due_date_shifted" and invoice_id, invoice_id, or reason: "started" |
Invoices
| Event | When | context |
|---|---|---|
invoice.created | Invoice issued, or replacement invoice | subscription_id, replaces_invoice_id |
invoice.paid | Invoice settled | source (push, page, manual, credit), payin_id, track_id, invoice_payment_id, amount, credited |
invoice.payment_failed | A mobile money payment on the invoice failed or expired | payin_id, track_id, reason, source |
invoice.voided | Invoice voided, by you or when the subscription ended | reason (merchant_request or subscription_cancelled), replaced_by, cancellation_reason |
invoice.uncollectible | Invoice left unpaid until the subscription ended, sent with subscription.cancelled | |
invoice.updated | Due date postponed, credit partially applied, or duplicate payment turned into credit | reason (due_date_shifted, duplicate_payment), payment details |
Customers
| Event | When | context |
|---|---|---|
customer.created | Customer created | source: api, import or signup_link |
customer.updated | Customer updated, contact added or removed, preferred contact changed or channel resubscribed from the portal | contact_id, change (contact_added, contact_removed, preferred_contact, contact_opted_in), channel, source: "portal" from the portal |
customer.contact_verified | Contact confirmed by code, through a subscription link, or reached for the first time | source: otp, signup_link or delivery, channel |
customer.contact_unreachable | Contact became unreachable | reason, consecutive_failures, error_code, channel |
customer.contact_opted_out | The customer no longer wants messages on this channel | source: whatsapp or portal, channel |
“Verified” or “reachable”
customer.contact_verified with context.source: "delivery" means a message was delivered: the contact becomes reachable, but its verified field stays false. Only a one-time code or a subscription link makes a contact verified.
Example: invoice paid
{
"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
}
}
}It is followed by subscription.renewed (here, the subscription was past_due). credited gives the part of the payment turned into credit for the customer, in case of an overpayment.
How is this guide?
Last updated on