Webhooks

​

Add an endpoint

​

Verify the signature

Ledger-Signature: t=1762539631,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

import { verifyWebhook, WebhookSignatureError } from "integrateledger/webhooks";

export async function POST(request: Request): Promise<Response> {
  let event;
  try {
    event = await verifyWebhook({
      payload: await request.text(),
      signature: request.headers.get("ledger-signature"),
      secret: process.env.LEDGER_WEBHOOK_SECRET ?? "",
    });
  } catch (error) {
    if (error instanceof WebhookSignatureError) {
      return new Response("Invalid signature", { status: 400 });
    }
    throw error;
  }
  await queueForProcessing(event); // answer fast; do the work afterwards
  return new Response(null, { status: 200 });
}

import os
from flask import Flask, abort, request
from integrateledger import WebhookSignatureError, verify_webhook

app = Flask(__name__)

@app.post("/webhooks/ledger")
def ledger_webhook():
    try:
        event = verify_webhook(
            request.get_data(),
            request.headers.get("Ledger-Signature"),
            os.environ["LEDGER_WEBHOOK_SECRET"],
        )
    except WebhookSignatureError:
        abort(400)
    queue_for_processing(event)  # answer fast; do the work afterwards
    return "", 200

​

Handle the event

{
  "id": "evt_3QeV8vK2mN7pL1xR9sT4uW6y",
  "object": "event",
  "type": "subscription.created",
  "apiVersion": "2026-11-07",
  "created": "2026-11-07T18:20:31.000Z",
  "livemode": false,
  "environment": "sandbox",
  "data": {
    "object": {
      "object": "subscription",
      "id": 42,
      "customerId": "user_123",
      "planId": "pro",
      "planName": "Pro",
      "monthlyPriceCents": 4900,
      "monthlyCredits": 1000,
      "status": "active",
      "currentPeriodStart": "2026-11-07T18:20:05.000Z",
      "currentPeriodEnd": "2026-12-07T18:20:05.000Z",
      "createdAt": "2026-11-07T18:19:12.000Z"
    }
  }
}

• id is the same on every retry of an event. Store it and skip events you’ve already handled.
• created is when the change happened, not when the request was sent.
• apiVersion names the shape. A breaking change ships as a new version; an endpoint keeps the version it was created with.
• Order isn’t guaranteed. A retry can arrive after a later event. Compare created, or read the current state from the API, before acting on an old event.
• Return a 2xx within 10 seconds. Do the work after you answer: anything else (a redirect, a 4xx, a 5xx, a timeout) counts as a failure.

​

Events

​

Low and depleted balances

• balance.low is off until you set a threshold in credits under Settings › Webhooks › Low balance alert (one per environment). It fires when a use crosses the threshold, once; it fires again only after the balance goes back above it (a renewal or a credit pack) and crosses again.
• balance.depleted fires on the first refused request in the customer’s billing period (the plan’s period, or the calendar month in UTC for a customer without a plan). Later refusals in that period send nothing.

​

Retries and turned-off endpoints