Format & Signature

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 both X-Lago-Signature and X-Lago-Signature-Algorithm 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. You can choose between 2 differents signatures algorithm during your webhook endpoints creation, hmac or jwt. Please note that jwt is our original signature and is used by default.

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()

import Client from "lago-nodejs-client";

let client = new Client("__YOUR_API_KEY__");
let webhooksPublicKey = client.webhookPublicKey();

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

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_API_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_API_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_API_KEY', request.body)
base64_hmac = Base64.strict_encode64(hmac)

base64_hmac == signature

​Message format

​Signature

​JWT Signature

​1. Retrieve the public key

​2. Decode and validate the signature

​HMAC Signature

​Decode and validate the signature

Message format

Signature

JWT Signature

1. Retrieve the public key

2. Decode and validate the signature

HMAC Signature

Decode and validate the signature