Skip to main content
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