Logo GenukaGenuka Pay
API ReferenceSubscriptions

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" }
  }
}
  • data is the object concerned, as returned by the API: subscription (with customer as an ID), invoice (with customer and payments), customer (with its contacts) or contact. The excerpt above is abridged.
  • data.previous_attributes gives the previous value of the fields that changed. Absent when nothing changed.
  • data.context gives the context of the event, when there is one.
  • id identifies the delivery: a retry keeps the same id. It is also sent in the X-Webhook-Id header, and the event name in X-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 2xx within 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.paid then subscription.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

EventWhencontext
subscription.createdSubscription created, as incomplete or trialing (active for an import)source, import_id for an import
subscription.activatedFirst payment received: incomplete or trialing → activeinvoice_id
subscription.renewedRenewal paid, new period opened (from active or past_due)invoice_id
subscription.trial_will_endThe trial ends in 3 days. Sent once.trial_ends_at
subscription.past_dueDue date passed by one day, or trial ended without payment. Access is kept.invoice_id, due_at
subscription.suspendedGrace period over, access is cut offinvoice_id, due_at
subscription.reactivatedPayment received during suspension, access is restoredinvoice_id
subscription.cancellation_scheduledCancellation scheduled for the end of the periodreason, cancel_at
subscription.cancellation_withdrawnScheduled cancellation withdrawn
subscription.cancelledSubscription ended. The cause is in cancellation_reason: customer_request, merchant_request, unpaid or incomplete_expired.reason, invoice_id for non-payment
subscription.completedLast paid period of a fixed-term price has ended
subscription.updatedPayment 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 datereason: "due_date_shifted" and invoice_id, invoice_id, or reason: "started"

Invoices

EventWhencontext
invoice.createdInvoice issued, or replacement invoicesubscription_id, replaces_invoice_id
invoice.paidInvoice settledsource (push, page, manual, credit), payin_id, track_id, invoice_payment_id, amount, credited
invoice.payment_failedA mobile money payment on the invoice failed or expiredpayin_id, track_id, reason, source
invoice.voidedInvoice voided, by you or when the subscription endedreason (merchant_request or subscription_cancelled), replaced_by, cancellation_reason
invoice.uncollectibleInvoice left unpaid until the subscription ended, sent with subscription.cancelled
invoice.updatedDue date postponed, credit partially applied, or duplicate payment turned into creditreason (due_date_shifted, duplicate_payment), payment details

Customers

EventWhencontext
customer.createdCustomer createdsource: api, import or signup_link
customer.updatedCustomer updated, contact added or removed, preferred contact changed or channel resubscribed from the portalcontact_id, change (contact_added, contact_removed, preferred_contact, contact_opted_in), channel, source: "portal" from the portal
customer.contact_verifiedContact confirmed by code, through a subscription link, or reached for the first timesource: otp, signup_link or delivery, channel
customer.contact_unreachableContact became unreachablereason, consecutive_failures, error_code, channel
customer.contact_opted_outThe customer no longer wants messages on this channelsource: 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