API reference

Webhook Endpoints

get/v1/webhook-endpoints

List webhook endpoints

webhook_endpoints.listread tokenidempotent

The ledger's webhook endpoints. Secrets are never listed.

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
X-Organization-Id string \| null · header

Returns 200 · WebhookEndpointList

data array of WebhookEndpoint · required
has_more boolean · required
next_cursor string \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/webhook-endpoints" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

post/v1/webhook-endpoints

Create a webhook endpoint

webhook_endpoints.createwrite tokenidempotent

Start pushing the ledger's changes of change_types to url. The response carries the signing secret, shown this once: store it and verify every delivery's LumaLedger-Signature with it. Changes from before the endpoint existed are not pushed (read them from changes.list). A ledger may have up to 16 endpoints.

Parameters

Idempotency-Key string \| null · header	Any unique string (a UUID is ideal). A retry with the same key returns the first attempt's response instead of doing the work twice. Keys are kept for 24 hours.
X-Organization-Id string \| null · header

Body · WebhookEndpointCreate

change_types array of string · required	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
description string \| null	A note for yourself: what receives these.
url string · required	An https URL on the public internet. Its host may not resolve to a private, loopback, link-local or otherwise internal address; this is checked now and again before every delivery. Redirects are not followed.

Returns 201 · WebhookEndpointWithSecret

change_types array of string · required	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
created_at datetime · required
description string \| null · required
disabled_reason string \| null · required	Why it is disabled: `failing` (by us) or `user`. Null while enabled.
failing_since datetime \| null · required	The first failed delivery since the last one it accepted. Null when healthy.
id integer · required	The endpoint id (`webhook_endpoint_id` in paths).
secret string \| null · required	The signing secret (`whsec_…`): verify `LumaLedger-Signature` with it. Shown only in this response and never again; `webhook_endpoints.rotate_secret` issues a new one. Null on a replayed `Idempotency-Key` response.
status string · required	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
updated_at datetime · required
url string · required

Example

curl -X POST "https://api.lumaledger.app/v1/webhook-endpoints" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "change_types": [
      "…"
    ],
    "url": "…"
  }'

delete/v1/webhook-endpoints/{webhook_endpoint_id}

Delete a webhook endpoint

webhook_endpoints.deletewrite tokendestructiveidempotent

Stop pushing to this endpoint, and drop what it is still owed. The change feed is unaffected.

Parameters

webhook_endpoint_id integer · path · required
X-Organization-Id string \| null · header

Returns 204 with no body.

Example

curl -X DELETE "https://api.lumaledger.app/v1/webhook-endpoints/{webhook_endpoint_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/webhook-endpoints/{webhook_endpoint_id}

Get a webhook endpoint

webhook_endpoints.getread tokenidempotent

One webhook endpoint, with whether it is failing. The secret is not shown.

Parameters

webhook_endpoint_id integer · path · required
X-Organization-Id string \| null · header

Returns 200 · WebhookEndpoint

change_types array of string · required	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
created_at datetime · required
description string \| null · required
disabled_reason string \| null · required	Why it is disabled: `failing` (by us) or `user`. Null while enabled.
failing_since datetime \| null · required	The first failed delivery since the last one it accepted. Null when healthy.
id integer · required	The endpoint id (`webhook_endpoint_id` in paths).
status string · required	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
updated_at datetime · required
url string · required

Example

curl -X GET "https://api.lumaledger.app/v1/webhook-endpoints/{webhook_endpoint_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

patch/v1/webhook-endpoints/{webhook_endpoint_id}

Update a webhook endpoint

webhook_endpoints.updatewrite tokenidempotent

Change an endpoint's URL, description or change types, or turn it off and on. Only the fields sent change. Turning a disabled endpoint back on clears its failure record; what it missed meanwhile is in changes.list, not re-sent.

Parameters

webhook_endpoint_id integer · path · required
X-Organization-Id string \| null · header

Body · WebhookEndpointUpdate

change_types array of string \| null	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
description string \| null
status string \| null	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
url string \| null	An https URL on the public internet. Its host may not resolve to a private, loopback, link-local or otherwise internal address; this is checked now and again before every delivery. Redirects are not followed.

Returns 200 · WebhookEndpoint

change_types array of string · required	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
created_at datetime · required
description string \| null · required
disabled_reason string \| null · required	Why it is disabled: `failing` (by us) or `user`. Null while enabled.
failing_since datetime \| null · required	The first failed delivery since the last one it accepted. Null when healthy.
id integer · required	The endpoint id (`webhook_endpoint_id` in paths).
status string · required	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
updated_at datetime · required
url string · required

Example

curl -X PATCH "https://api.lumaledger.app/v1/webhook-endpoints/{webhook_endpoint_id}" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

post/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret

Rotate a webhook endpoint's signing secret

webhook_endpoints.rotate_secretwrite token

Issue a new signing secret, shown in this response only. For the next 24 hours deliveries carry two v1 signatures, one per secret, so a receiver can switch over without refusing any; after that only the new secret signs.

Parameters

webhook_endpoint_id integer · path · required
X-Organization-Id string \| null · header

Returns 200 · WebhookEndpointWithSecret

change_types array of string · required	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
created_at datetime · required
description string \| null · required
disabled_reason string \| null · required	Why it is disabled: `failing` (by us) or `user`. Null while enabled.
failing_since datetime \| null · required	The first failed delivery since the last one it accepted. Null when healthy.
id integer · required	The endpoint id (`webhook_endpoint_id` in paths).
secret string \| null · required	The signing secret (`whsec_…`): verify `LumaLedger-Signature` with it. Shown only in this response and never again; `webhook_endpoints.rotate_secret` issues a new one. Null on a replayed `Idempotency-Key` response.
status string · required	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
updated_at datetime · required
url string · required

Example

curl -X POST "https://api.lumaledger.app/v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

Objects

WebhookEndpoint

Fields

change_types array of string · required	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
created_at datetime · required
description string \| null · required
disabled_reason string \| null · required	Why it is disabled: `failing` (by us) or `user`. Null while enabled.
failing_since datetime \| null · required	The first failed delivery since the last one it accepted. Null when healthy.
id integer · required	The endpoint id (`webhook_endpoint_id` in paths).
status string · required	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
updated_at datetime · required
url string · required

WebhookEndpointCreate

Fields

change_types array of string · required	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
description string \| null	A note for yourself: what receives these.
url string · required	An https URL on the public internet. Its host may not resolve to a private, loopback, link-local or otherwise internal address; this is checked now and again before every delivery. Redirects are not followed.

WebhookEndpointList

A page of webhook endpoints, in id order.

Fields

data array of WebhookEndpoint · required
has_more boolean · required
next_cursor string \| null · required

WebhookEndpointUpdate

Only the fields sent change.

Fields

change_types array of string \| null	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
description string \| null
status string \| null	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
url string \| null	An https URL on the public internet. Its host may not resolve to a private, loopback, link-local or otherwise internal address; this is checked now and again before every delivery. Redirects are not followed.

WebhookEndpointWithSecret

An endpoint, with the signing secret shown this once.

Fields

change_types array of string · required	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
created_at datetime · required
description string \| null · required
disabled_reason string \| null · required	Why it is disabled: `failing` (by us) or `user`. Null while enabled.
failing_since datetime \| null · required	The first failed delivery since the last one it accepted. Null when healthy.
id integer · required	The endpoint id (`webhook_endpoint_id` in paths).
secret string \| null · required	The signing secret (`whsec_…`): verify `LumaLedger-Signature` with it. Shown only in this response and never again; `webhook_endpoints.rotate_secret` issues a new one. Null on a replayed `Idempotency-Key` response.
status string · required	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
updated_at datetime · required
url string · required

change_types array of string \| null	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
description string \| null
status string \| null	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
url string \| null	An https URL on the public internet. Its host may not resolve to a private, loopback, link-local or otherwise internal address; this is checked now and again before every delivery. Redirects are not followed.

change_types array of string \| null	The change types to deliver: any of `transaction.created`, `transaction.updated`, `transaction.deleted`, `account.balance_updated`, `budget.exceeded`, `import.completed`, `job.completed`, or `*` for every type, including ones added later.
description string \| null
status string \| null	`enabled` or `disabled`. An endpoint that has not accepted a delivery for three days is disabled for you (`disabled_reason: failing`) and the ledger's owners are emailed; set it back to `enabled` once it answers.
url string \| null	An https URL on the public internet. Its host may not resolve to a private, loopback, link-local or otherwise internal address; this is checked now and again before every delivery. Redirects are not followed.