All Docs
FeaturesCalmony PayUpdated March 14, 2026

Invoice Webhook Events

Invoice Webhook Events

Calmony Pay dispatches webhook events at each stage of an invoice's lifecycle, giving your application real-time visibility into invoice creation, payment success, and payment failure.

Overview

EventTrigger
invoice.createdAn invoice is generated
invoice.paidPayment against the invoice succeeds
invoice.payment_failedA subscription billing attempt fails

Event Details

invoice.created

Fired immediately when an invoice is generated — either manually or automatically as part of a subscription billing cycle.

Use cases:

  • Record the invoice in your own database
  • Send the customer a "Your invoice is ready" notification
  • Trigger pre-payment approval workflows

Example payload:

{
  "event": "invoice.created",
  "created_at": "2025-01-15T10:00:00Z",
  "data": {
    "invoice_id": "inv_abc123",
    "customer_id": "cus_xyz456",
    "amount": 4999,
    "currency": "GBP",
    "status": "open"
  }
}

invoice.paid

Fired when a payment against an invoice is successfully collected.

Use cases:

  • Fulfil an order or grant access to a resource
  • Update subscription status to active
  • Send a payment receipt to the customer

Example payload:

{
  "event": "invoice.paid",
  "created_at": "2025-01-15T10:05:00Z",
  "data": {
    "invoice_id": "inv_abc123",
    "customer_id": "cus_xyz456",
    "amount": 4999,
    "currency": "GBP",
    "status": "paid"
  }
}

invoice.payment_failed

Fired when a subscription billing attempt fails — for example due to an expired card or insufficient funds.

Use cases:

  • Trigger a dunning / retry flow
  • Notify the customer to update their payment method
  • Pause or restrict access to the service

Example payload:

{
  "event": "invoice.payment_failed",
  "created_at": "2025-01-15T10:05:00Z",
  "data": {
    "invoice_id": "inv_abc123",
    "customer_id": "cus_xyz456",
    "amount": 4999,
    "currency": "GBP",
    "status": "payment_failed",
    "failure_reason": "insufficient_funds"
  }
}

Handling Invoice Events

Register a webhook endpoint in the Calmony Pay dashboard, then update your handler to process each event type:

app.post('/webhooks/calmony', (req, res) => {
  const event = req.body;

  switch (event.event) {
    case 'invoice.created':
      // Record or notify on invoice generation
      handleInvoiceCreated(event.data);
      break;

    case 'invoice.paid':
      // Fulfil order, activate subscription
      handleInvoicePaid(event.data);
      break;

    case 'invoice.payment_failed':
      // Trigger dunning, notify customer
      handleInvoicePaymentFailed(event.data);
      break;

    default:
      // Safely ignore unhandled events
      break;
  }

  res.status(200).send('OK');
});

Tip: Always return a 200 response promptly. If your handler takes longer than expected, acknowledge the webhook immediately and process it asynchronously.

Event Ordering

Invoice events follow this sequence for a successful payment:

invoice.created  →  invoice.paid

For a failed subscription billing attempt:

invoice.created  →  invoice.payment_failed

If a failed invoice is later retried and succeeds, you will receive:

invoice.created  →  invoice.payment_failed  →  invoice.paid

Related