Subscription Lifecycle Webhooks

Calmony Pay dispatches webhook events at every stage of a subscription's life. This lets your application react in real time to subscription changes without polling the API.

Supported events

Event	Description
subscription.created	Fired when a new subscription is created
subscription.updated	Fired when a subscription is modified
subscription.deleted	Fired when a subscription is cancelled
invoice.payment_failed	Fired when the billing cron fails to collect payment

---

Event reference

subscription.created

Dispatched immediately after a subscription is created.

{
  "event": "subscription.created",
  "data": {
    "id": "sub_xxxxxxxxxxxxxxxx",
    "status": "active",
    "customer_id": "cus_xxxxxxxxxxxxxxxx",
    "plan_id": "plan_xxxxxxxxxxxxxxxx",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

subscription.updated

Dispatched whenever mutable fields on a subscription are changed — for example, a plan upgrade, quantity adjustment, or status transition.

{
  "event": "subscription.updated",
  "data": {
    "id": "sub_xxxxxxxxxxxxxxxx",
    "status": "active",
    "customer_id": "cus_xxxxxxxxxxxxxxxx",
    "plan_id": "plan_yyyyyyyyyyyyyyyy",
    "updated_at": "2025-01-02T00:00:00Z"
  }
}

subscription.deleted

Dispatched when a subscription is cancelled. This fires once the cancellation is processed, whether the cancellation took effect immediately or at the end of the billing period.

{
  "event": "subscription.deleted",
  "data": {
    "id": "sub_xxxxxxxxxxxxxxxx",
    "status": "cancelled",
    "customer_id": "cus_xxxxxxxxxxxxxxxx",
    "cancelled_at": "2025-01-03T00:00:00Z"
  }
}

invoice.payment_failed

Dispatched by the billing cron job when a payment attempt against a subscription invoice is declined or otherwise unsuccessful. Use this event to trigger dunning flows, notify your customer, or pause access.

{
  "event": "invoice.payment_failed",
  "data": {
    "invoice_id": "inv_xxxxxxxxxxxxxxxx",
    "subscription_id": "sub_xxxxxxxxxxxxxxxx",
    "customer_id": "cus_xxxxxxxxxxxxxxxx",
    "amount": 2900,
    "currency": "GBP",
    "failure_reason": "insufficient_funds",
    "attempted_at": "2025-01-04T00:00:00Z"
  }
}

---

Handling events

Your webhook endpoint should return a 2xx HTTP status to acknowledge receipt. Any non-2xx response is treated as a failure and the event will be retried.

HTTP/1.1 200 OK

Process events idempotently — the same event may be delivered more than once in the case of retries.

Recommended flows

Event	Suggested action
subscription.created	Provision access, send a welcome email
subscription.updated	Adjust feature entitlements, notify the customer
subscription.deleted	Revoke access, send a cancellation confirmation
invoice.payment_failed	Start a dunning sequence, email the customer to update payment details

---

Configuring webhook endpoints

Webhook endpoints and the event types they receive are configured in the Calmony Pay dashboard or via the Webhooks API. Your endpoint will only receive the new subscription event types if it is explicitly subscribed to them.