Messages - Lago

Alerts

alerts.triggered

data.object

Triggered alert object. Sent when a new usage alert threshold has been crossed.

Credit notes and refunds

credit_note.created

data.object

Credit note object. Sent when a new credit note has been issued for a customer. This will allow your application to proceed with the refund.

credit_note.generated

data.object

Credit note object. Sent when the PDF file has been generated for a credit note. This will allow your application to retrieve the PDF credit note.

credit_note.refund_failure

data.object

credit_note_payment_provider_refund_error object. Sent when there is an error related to the refund process (i.e. the payment provider cannot refund the customer).

Customers

Basic customer information

customer.created

data.object

Customer object. Sent when a customer is successfully created in Lago.

customer.updated

data.object

Customer object. Sent when a customer is successfully updated in Lago.

External payment providers

customer.payment_provider_created

data.object

Customer object. Sent when a customer is successfully created in the payment provider’s application. This allows you to retrieve the identifier assigned to the customer by the payment service provider.

customer.checkout_url_generated

data.object

payment_provider_customer_checkout_url object. Sent when a checkout link is issued for a customer.

customer.payment_provider_error

data.object

payment_provider_customer_error object. Sent when there is an error related to the creation of a customer in the payment provider’s system.

invoice.payment_failure

data.object

payment_provider_invoice_payment_error object. Sent when there is an error related to the payment process. Usually occurs when no valid payment method is defined for the customer in the payment service provider’s application.

invoice.payment_dispute_lost

data.object

payment_dispute_lost object. Sent whenever a dispute or a chargeback is lost within your payment provider.

External accounting providers

customer.accounting_provider_created

data.object

Customer object. Sent when a customer is successfully created in the accounting provider’s application (like NetSuite). This allows you to retrieve the identifier assigned to the customer by the accounting service provider.

customer.accounting_provider_error

data.object

accounting_provider_customer_error object. Sent when there is an error related to the accounting provider sync. Usually occurs when something went wrong in the accounting service provider’s application.

External tax providers

customer.tax_provider_error

data.object

tax_provider_error object. Sent when there is an error related to the tax provider sync. This usually occurs due to issues with item mappings, customer definitions, or within the service provider’s application.

Event ingestion

events.errors

data.object

Sent by the health check process when some events received in the previous hour do not match the validation rules.

events.error

data.object

deprecated

This webhook is deprecated and no longer sent in Lago v0.50.0-beta and above. It was sent when there was an error related to the creation of an event.

Invoices

invoice.drafted

data.object

Invoice object. Sent when a new invoice is in draft.

invoice.created

data.object

Invoice object. Sent when an invoice is finalized. This event serves as a signal to your application that the invoice processing is complete and you can proceed with the necessary billing actions or procedures.

invoice.one_off_created

data.object

Invoice object. Sent when a one-off invoice is created. Only add-ons can be applied to one-off invoices.

invoice.paid_credit_added

data.object

Invoice object. Sent when prepaid credits have been paid and added to the customer’s wallet. You can use this information to generate a PDF invoice or collect the payment.

invoice.generated

data.object

Invoice object. Sent when the PDF file has been generated for a customer invoice. This will allow your application to retrieve the PDF invoice.

invoice.payment_status_updated

data.object

Invoice object. Sent when the payment status of an invoice is updated based on information provided by the payment provider.

invoice.payment_overdue

data.object

Invoice object. Sent when the payment of an invoice is considered as overdue.

invoice.voided

data.object

Invoice object. Sent when an invoice is voided.

Payments

payment.requires_action

data.object

This message is triggered when a payment requires additional validation or confirmation, typically via 3D Secure (3DS). This is commonly seen in regions like India or when enhanced customer authentication is necessary. The url field contains the checkout link that initiates 3D Secure (3DS) validation for your customers. The return_url is the page displayed once the 3DS process is completed.

payment_request.created

data.object

Payment request object. Sent when a manual payment request has been triggered, to request payment for the overdue balance.

payment_request.payment_failure

data.object

Payment request object. Sent when the payment attached to a payment request has failed. The provider_error field indicates the error code and message from the payment provider.

payment_request.payment_status_updated

data.object

Payment request object. Sent when the payment attached to a payment request is updated to a new payment status, through the `payment_status field.

Payment receipts

payment_receipt.created

data.object

Payment receipt object. Sent when a payment receipt is created. This event serves as a signal to your application that the receipt creation is complete and the payment has been recorded.

payment_receipt.generated

data.object

Payment receipt object. Sent when the PDF file has been generated for a payment receipt. This will allow your application to retrieve the PDF receipt.

Subscriptions and fees

fee.created

data.object

Fee object. Sent when a fee for a charge to be paid in advance is created. You can use this information to collect the payment of the pay_in_advance fee. Useful for fintech companies that need to create a statement of transactions without invoicing.

subscription.started

data.object

Subscription object. Sent when a subscription starts. The previous_plan_code argument is filled if the subscription has been upgraded or downgraded.

subscription.termination_alert

data.object

Subscription object. Alert for imminent termination of subscriptions with set end dates, sent 45 days and 15 days prior (at fixed intervals).

subscription.terminated

data.object

Subscription object. Sent when a subscription is terminated. The next_plan_code argument is filled if the subscription has been upgraded or downgraded.

subscription.trial_ended

data.object

Subscription object. Sent when the free trial is ended for a subscription.

subscription.usage_threshold_reached

data.object

Subscription object. Sent when a progressive billing threshold has been crossed.

Wallets and prepaid credits

wallet.created

data.object

Wallet object. Sent when a wallet is created.

wallet.updated

data.object

Wallet object. Sent when a wallet is updated. Please note that you won’t receive this message if the wallet’s ongoing balance is updated.

wallet.terminated

data.object

Wallet object. Sent when a wallet is terminated.

wallet.depleted_ongoing_balance

data.object

Wallet object. Sent when the ongoing balance is negative or equal to 0.

wallet_transaction.created

data.object

Wallet transaction object. Sent when a wallet transaction is created. For example, when new credits have been paid or offered.

wallet_transaction.updated

data.object

Wallet transaction object. Sent when a wallet transaction is updated. For example, when wallet transaction is marked as settled.

wallet_transaction.payment_failure

data.object

Sent when a wallet transaction payment is declined.

Payload example

{
  "webhook_type": "wallet_transaction.payment_failure",
  "object_type": "payment_provider_wallet_transaction_payment_error",
  "payment_provider_wallet_transaction_payment_error": {
    "lago_wallet_transaction_id": "4df9ef1d-d13b-4ff1-850d-ca89f0c0f9fb",
    "lago_customer_id": "90a33125-0c2d-4117-8978-cfb367487783",
    "external_customer_id": "paymentfailure",
    "provider_customer_id": "cus_RVCkzr7PASt28882",
    "payment_provider": "stripe",
    "payment_provider_code": "stripe_prod",
    "provider_error": {
      "message": "Your card was declined.",
      "error_code": "card_declined"
    }
  }
}

API Reference

​Alerts

​Credit notes and refunds

​Customers

​Basic customer information

​External payment providers

​External accounting providers

​External tax providers

​Event ingestion

​Invoices

​Payments

​Payment receipts

​Subscriptions and fees

​Wallets and prepaid credits

Alerts

Credit notes and refunds

Customers

Basic customer information

External payment providers

External accounting providers

External tax providers

Event ingestion

Invoices

Payments

Payment receipts

Subscriptions and fees

Wallets and prepaid credits