Messages

Here is the exhaustive list of webhook messages triggered by Lago.

Sent when a new invoice has been emitted for a customer.

This will allow your application to proceed with the billing.

{
  "webhook_type": "invoice.created",
  "object_type": "invoice",
  "invoice": {
    "lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "sequential_id": 2,
    "number": "LAG-1234-001-002",
    "from_date": "2022-04-01",
    "to_date": "2022-04-30",
    "charges_from_date": "2022-04-01",
    "issuing_date": "",
    "amount_cents": 100,
    "amount_currency": "EUR",
    "vat_amount_cents": 20,
    "vat_amount_currency": "EUR",
    "total_amount_cents": 120,
    "total_amount_currency": "EUR",
    "file_url": "https://getlago.com/invoice/file",
    "customer": {
      "lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
      "sequential_id": 1,
      "slug": "LAG-1234-001",
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "address_line1": "5230 Penfield Ave",
      "address_line2": null,
      "city": "Woodland Hills",
      "country": "US",
      "created_at": "2022-04-29T08:59:51Z",
      "email": "dinesh@piedpiper.test",
      "legal_name": "Coleman-Blair",
      "legal_number": "49-008-2965",
      "logo_url": "http://hooli.com/logo.png",
      "name": "Gavin Belson",
      "phone": "1-171-883-3711 x245",
      "state": "CA",
      "url": "http://hooli.com",
      "vat_rate": 20.0,
      "zipcode": "91364"
    },
    "subscriptions": [
        {
        "lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
        "external_id": "susbcription_external_id",
        "lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
        "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "canceled_at": "2022-04-29T08:59:51Z",
        "created_at": "2022-04-29T08:59:51Z",
        "plan_code": "new_code",
        "started_at": "2022-04-29T08:59:51Z",
        "status": "active",
        "terminated_at": null
      }
    ],
    "fees": [
      {
        "item": {
          "type": "subscription",
          "code": "plan_code",
          "name": "Plan"
        },
        "amount_cents": 100,
        "amount_currency": "EUR",
        "vat_amount_cents": 20,
        "vat_amount_currency": "EUR",
        "units": "0.32",
        "events_count": 23
      }
    ],
    "credits": [
      {
        "item": {
          "type": "coupon",
          "code": "coupon_code",
          "name": "Coupon"
        },
        "amount_cents": 100,
        "amount_currency": "EUR"
      }
    ]
  }
}

Attributes	Description
invoice JSON Not nullable	Invoice object

Sent when the PDF file has been generated for a customer invoice.

This will allow your application to retrieve the PDF invoice.

{
  "webhook_type": "invoice.generated",
  "object_type": "invoice",
  "invoice": {
    "lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "sequential_id": 2,
    "number": "LAG-1234-001-002",
    "from_date": "2022-04-01",
    "to_date": "2022-04-30",
    "charges_from_date": "2022-04-01",
    "issuing_date": "",
    "amount_cents": 100,
    "amount_currency": "EUR",
    "vat_amount_cents": 20,
    "vat_amount_currency": "EUR",
    "total_amount_cents": 120,
    "total_amount_currency": "EUR",
    "file_url": "https://getlago.com/invoice/file",
  }
}

Attributes	Description
invoice JSON Not nullable	Invoice object

Sent when an add-on has been applied to customer. The invoice is created immediately after the add-on is assigned to a customer.

You can use this information to generate a PDF invoice or collect the payment.

{
  "webhook_type": "invoice.add_on_added",
  "object_type": "invoice",
  "invoice": {
    "lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "sequential_id": 2,
    "from_date": "2022-04-30",
    "to_date": "2022-04-30",
    "issuing_date": "2022-04-30",
    "amount_cents": 100,
    "amount_currency": "EUR",
    "vat_amount_cents": 20,
    "vat_amount_currency": "EUR",
    "total_amount_cents": 120,
    "total_amount_currency": "EUR",
    "customer": {
      "lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "address_line1": "5230 Penfield Ave",
      "address_line2": null,
      "city": "Woodland Hills",
      "country": "US",
      "created_at": "2022-04-29T08:59:51Z",
      "email": "dinesh@piedpiper.test",
      "legal_name": "Coleman-Blair",
      "legal_number": "49-008-2965",
      "logo_url": "http://hooli.com/logo.png",
      "name": "Gavin Belson",
      "phone": "1-171-883-3711 x245",
      "state": "CA",
      "url": "http://hooli.com",
      "vat_rate": 20.0,
      "zipcode": "91364"
    },
    "subscription": {
      "lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
      "external_id": "susbcription_external_id",
      "lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
      "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "canceled_at": "2022-04-29T08:59:51Z",
      "created_at": "2022-04-29T08:59:51Z",
      "plan_code": "new_code",
      "started_at": "2022-04-29T08:59:51Z",
      "status": "active",
      "terminated_at": null
    },
    "fees": [
      {
        "item": {
          "type": "add_on",
          "code": "add_on_code",
          "name": "add_on_name"
        },
        "amount_cents": 100,
        "amount_currency": "EUR",
        "vat_amount_cents": 20,
        "vat_amount_currency": "EUR",
        "units": "1",
        "events_count": 23
      }
    ]
  }
}

Attributes	Description
invoice JSON Not nullable	Invoice 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.

{
  "webhook_type": "invoice.payment_failure",
  "object_type": "payment_provider_invoice_payment_error",
  "payment_provider_invoice_payment_error": {
    "lago_invoice_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "provider_customer_id": "cus_123456",
    "payment_provider": "stripe",
    "provider_error": {
      "message": "Cannot charge a customer that has no active card",
      "error_code": "missing"
    }
  }
}

Attributes	Description
lago_invoice_id String Not null	Unique identifer of the invoice in Lago application
lago_customer_id String Not null	Unique identifer of the customer in Lago application
external_customer_id String Not null	Unique identifer of the customer in your application
provider_customer_id String Not null	Unique identifer of the customer in payment provider application
payment_provider String	Payment provider used to process the payment
provider_error[message] String	Error message sent by the payment provider
provider_error[error_code] String	Error code sent by the payment provider

This webhook is sent when there is an error related to the creation of an event.

{
  "webhook_type": "event.error",
  "object_type": "event_error",
  "event_error": {
    "status": 422,
    "error": "Unprocessable entity",
    "message": "code does not exist",
    "input_params": {
      "transaction_id": "__transaction_id__",
      "external_customer_id": "customer123",
      "code": "code123"
    }
  }
}

Attributes	Description
status String Not null	HTTP status of the error. Possible statuses are `404` or `422`
error String Not null	HTTP error code. Possible errors are `Not found` or `Unprocessable entity`
message String Not null	Error code. See next list for the description of each error code.
input_params JSON Not null	JSON provided at event creation

Code	Description
billable_metric_not_found 404	No billable metric matches the given code
customer_not_found 404	No customer matches the external id
subscription_not_found 404	No subscription matches the given external subscription id
invalid_argument 422	No subscription matches the given external subscription id
invalid_recurring_resource 422	Provided recurring resource for persisted event is invalid

This webhook is 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.

{
  "webhook_type": "customer.payment_provider_created",
  "object_type": "customer",
  "customer": {
    "lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
    "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "address_line1": "5230 Penfield Ave",
    "address_line2": null,
    "city": "Woodland Hills",
    "country": "US",
    "created_at": "2022-04-29T08:59:51Z",
    "email": "dinesh@piedpiper.test",
    "legal_name": "Coleman-Blair",
    "legal_number": "49-008-2965",
    "logo_url": "http://hooli.com/logo.png",
    "name": "Gavin Belson",
    "phone": "1-171-883-3711 x245",
    "state": "CA",
    "url": "http://hooli.com",
    "vat_rate": 12.5,
    "zipcode": "91364",
    "billing_configuration": {
      "payment_provider": "stripe",
      "provider_customer_id": "cus_12345"
    }
  }
}

Attributes	Description
customer JSON Not nullable	Customer object

This webhook is sent when there is an error related to the creation of a customer in the payment provider's application.

You should review the customer's data.

{
  "webhook_type": "invoice.payment_failure",
  "object_type": "payment_provider_customer_error",
  "payment_provider_customer_error": {
    "lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "payment_provider": "stripe",
    "provider_error": {
      "message": "Invalid email address",
      "error_code": "email_invalid"
    }
  }
}

Attributes	Description
lago_id String Not null	Unique identifer of the customer in Lago application
external_id String Not null	Unique identifer of the customer in your application
payment_provider String	Payment provider used to process the payment
provider_error[message] String	Error message sent by the payment provider
provider_error[error_code] String	Error code sent by the payment provider