Events & Webhooks

Every state change in Ledgerline emits an immutable event. Events are the backbone of the dashboard feed, your webhooks, and your audit history — one data model buys all three.

Your test keysk_test_…

The event object

Events are named resource.action and carry a full snapshot of the object at the moment it changed:

id — evt_1Qa…, immutable
type — e.g. invoice.paid, payment_link.created
created — ISO timestamp
data.object — the full resource snapshot

Event types

invoice.created	A new invoice was created.
invoice.finalized	The invoice is ready to be paid.
invoice.paid	Payment succeeded.
invoice.payment_failed	A charge was declined.
charge.succeeded	A card charge went through.
payment_link.created	A new payment link was created.
checkout.session.completed	Someone paid via a payment link.

List events

GET/v1/events

Newest first. This is exactly what the Workbench feed polls.

cURLNodePython

Subscribe from your app

GETstream

The SDK exposes a subscribe() helper that streams new events as they arrive — the same primitive the dashboard uses.

Node

// Stream new events — resolve them however you like
const stop = ll.events.subscribe((events) => {
  for (const e of events) {
    if (e.type === 'invoice.paid') fulfil(e.data.object)
  }
})

Webhook signatures

In production you receive events at your own HTTPS endpoint. Each request carries a Ledgerline-Signature: t=…,v1=… header — an HMAC-SHA256 of the timestamped payload keyed with your webhook secret. Verify it with a constant-time compare and reject anything older than 5 minutes to stop replays.

⚠

Stop-line: this reference build is test mode only — no real card networks and no real money move. Live delivery to your own endpoint is available once you connect a vault-granted key.