Format and signature

The messages are sent as a POST request to every webhook endpoint defined in the settings of your Lago organization. If you return an error (any response other than a 2xx) or if there is a network issue, the message is sent again. Lago attempts each message 3 times, waiting longer between each attempt.

Message format

POST __WEBHOOK_URL__

{
  "webhook_type": "__TYPE__",
  "object_type": "__OBJECT_TYPE__",
  "organization_id": "__ORGANIZATION_ID__",
  "__OBJECT_TYPE__": {}
}

The object_type field names the key that carries the object. For example, an invoice.created message has "object_type": "invoice" and an invoice key.

Unique key

Lago sends an idempotency key (a unique identifier) in the X-Lago-Unique-Key HTTP header. Use it to process a message only once.

Signature

Along with the payload, the message carries the X-Lago-Signature and X-Lago-Signature-Algorithm HTTP headers. They ensure the message comes from Lago and has not been altered. To verify the signature, decode it and compare the result with the body of the webhook. You choose between two signature algorithms when you create a webhook endpoint, hmac or jwt. The default is jwt.

JWT signature

1. Retrieve the public key

from lago_python_client import Client

client = Client(api_key='__YOUR_API_KEY__')
webhooks_public_key = client.webhooks().public_key()

const apiKey = "__YOUR_API_KEY__";

const response = await fetch(
  "https://api.getlago.com/api/v1/webhooks/json_public_key",
  { headers: { Authorization: `Bearer ${apiKey}` } }
);

const { webhook } = await response.json();
const webhooksPublicKey = webhook.public_key;

require 'json'
require 'net/http'

api_key = "__YOUR_API_KEY__"
uri = URI('https://api.getlago.com/api/v1/webhooks/json_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 = JSON.parse(response.body).dig('webhook', 'public_key')

You should persist the public key on your side to avoid querying it for each webhook.

2. Decode and validate the signature

import jwt

decoded_signature = jwt.decode(
  request.headers.get('X-Lago-Signature'),
  webhooks_public_key,
  algorithms=['RS256'],
  issuer="https://api.getlago.com"
)

decoded_signature['data'] == request.body

import jwt from "jsonwebtoken";

let token = request.header("X-Lago-Signature");

jwt.verify(
  token,
  webhooksPublicKey,
  {
    algorithms: ["RS256"],
    issuer: "https://api.getlago.com",
  },
  function (err, payload) {
    payload === request.body;
  }
);

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

HMAC signature

Decode and validate the signature

import hmac
import base64

calc_sig = hmac.new(LAGO_HMAC_KEY, request.body.encode(), 'sha256').digest()
base64_sig = base64.b64encode(calc_sig).decode()
request.headers.get('X-Lago-Signature') == base64_sig

import crypto from 'crypto';

const signature = request.header('X-Lago-Signature')
const hmac = crypto.createHmac('sha256', 'YOUR_ORGANIZATION_HMAC_KEY')

hmac.update(request.body)

const encodedBody = hmac.digest().toString('base64')

signature == encodedBody

require 'openssl'

signature =  request.headers['X-Lago-Signature']
hmac = OpenSSL::HMAC.digest('sha-256', 'YOUR_ORGANIZATION_HMAC_KEY', request.body)
base64_hmac = Base64.strict_encode64(hmac)

base64_hmac == signature

$signature = $_SERVER['X-Lago-Signature'];

$requestBody = file_get_contents('php://input');
$hmac = hash_hmac('sha256', $requestBody, 'YOUR_ORGANIZATION_HMAC_KEY', true);
$base64Signature = base64_encode($hmac);

$valid = hash_equals($signature, $base64Signature);