Skip to main content

Webhooks

Webhooks are HTTP notifications sent from Lago to your application.

The messages are sent as a POST to the URL defined in the settings of your Lago workspace.

Message format

POST __WEBHOOK_URL__

{
"webhook_type": "__TYPE__",
"object_type": "OBJECT_TYPE",
"__OBJECT__": {}
}

Signature

Allong with the payload the message contains a X-Lago-Signature HTTP header.

It is used to ensure the message is Coming from Lago and that the message has not been altered.

To verify the signature, you must decode the signature and compare the result with the body of the webhook.

  • Retrieve the public key:

    require 'net/http'

    api_key = "__YOUR_API_KEY__"
    uri = URI('https://api.getlago.com/api/v1/webhooks/public_key')

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    response = http.send_request(
    'GET',
    uri.request_uri,
    '',
    { 'Authorization' => "Bearer #{api_key}" }
    )

    webhooks_public_key = response.body
    tip

    You should persist the public key on you side to prevent querying it for each webhook

  • Decode and validate the signature:

    require 'openssl'
    require 'jwt'

    decoded_signature = JWT.decode(
    request.headers['X-Lago-Signature'],
    OpenSSL::PKey::RSA.new(Base64.decode64(webhooks_public_key)),
    true,
    {
    algorithm: 'RS256',
    iss: "https://api.getlago.com",
    verify_iss: true,
    },
    ).first

    decoded_signature['data'] == request.body

Messages

Invoice created

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

It will allow your application to perform the billing.

{
"webhook_type": "invoice.created",
"object_type": "invoice",
"invoice": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"sequential_id": 2,
"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",
"customer": {
"lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"customer_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",
"lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"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"
}
],
"credits": [
{
"item": {
"type": "coupon",
"code": "coupon_code",
"name": "Coupon"
},
"amount_cents": 100,
"amount_currency": "EUR"
}
]
}
}

Add-on applied to customer

Sent when an add-on has been applied to 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",
"customer_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",
"lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"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"
}
]
}
}

Event error

This webhook type is sent when there is an error with event creation.

{
"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__",
"customer_id": "customer123",
"code": "code123"
}
}
}
AttributesDescription
invoice     JSON     Not nullableInvoice object