Skip to content
Eternify Labs

Events, sent to you.

When something happens in the books, Eternify Ledger posts a short event to the endpoint you gave it. 31 events are listed below. A person adds an endpoint in the app, which also shows its signing secret.

A body that points.

An event names the record and says where to read it. It carries no amounts. The body is at most 2 KiB.

A bill.approved.v1 event
{
  "id": "evt_cmabc123",
  "type": "bill.approved.v1",
  "timestamp": "2026-10-17T00:00:00.000Z",
  "apiVersion": "v1",
  "ledgerId": "ledger_demo",
  "position": "184203",
  "data": {
    "object": {
      "type": "bill",
      "id": "bill_demo"
    },
    "href": "/v1/bills/bill_demo"
  }
}
  • id is the event’s own identifier. Keep it: a delivery can arrive twice, and the same id is the same event.
  • position is the event’s place in the ledger’s log.
  • data.href is the path to read the record, on the API address. Read it with your key to get the current state.
  • type ends in a version, so a new shape of an event can be told from the old one.

Check the signature.

Every delivery is signed with your endpoint's secret in the Standard Webhooks form, so a library for that form verifies ours. Verify the raw bytes, before any JSON parser has touched them.

Verify with the SDK
import { verifyWebhook } from "@eternify-labs/ledger/webhooks";

// rawBody is the exact bytes received, before any JSON parsing.
const event = await verifyWebhook(rawBody, request.headers, process.env.WEBHOOK_SECRET!);

The signed text is the delivery’s webhook-id, a full stop, its webhook-timestamp, a full stop and the raw body. The signature is the base64 of its HMAC-SHA256, keyed with the secret after its whsec_ prefix, decoded from base64. Each entry in webhook-signature reads v1, and the base64. During a secret rotation the header holds two entries, and either one passing is enough.

Reject a delivery whose timestamp is more than five minutes from your clock, and answer 2xx only after the check passes.

Paste a delivery into the signature checker to see which part does not match.

A test vector: the headers
webhook-id: evt_cmabc123
webhook-timestamp: 1792195200
webhook-signature: v1,Ud7Yyos7Fdjc683AxYjsPGi5ShlzB9laX8UFVDNY0lU=
A test vector: the secret and the body it signs
secret: whsec_YhZdna97/MW8AwSgNcHKGHFNnazXkhUuCOiGA/ChVG8=

{"id":"evt_cmabc123","type":"bill.approved.v1","timestamp":"2026-10-17T00:00:00.000Z","apiVersion":"v1","ledgerId":"ledger_demo","position":"184203","data":{"object":{"type":"bill","id":"bill_demo"},"href":"/v1/bills/bill_demo"}}

The secret above is a published test value that signs nothing real. A verifier given this body, these headers and this secret should accept them at a clock of 1792195200 seconds, and reject them if one character of the body changes.

If you don’t answer, we retry.

Answer with a 2xx status within 10 seconds. Anything else, or no answer, is tried again after a wait that grows, up to 8 attempts. A 410 tells us the endpoint is gone, and we pause it instead of retrying.

Wait before each retry
After attemptWait before the next
11 minute
25 minutes
330 minutes
42 hours
56 hours
612 hours
71 day

Each wait varies by up to 10% either way, so a burst of failures does not retry in step.

31 events, each with a read.

Each event names the operation that reads its record. A new event is added to this list in a release, and the changelog says so.

Events, with the operation that reads each record
EventWhat happenedRead the record with
bill.approved.v1Bill event: approved.getBillGET /v1/bills/{billId}
bill.declined.v1Bill event: declined.getBillGET /v1/bills/{billId}
bill.drafted.v1Bill event: drafted.getBillGET /v1/bills/{billId}
bill.held.v1Bill event: held.getBillGET /v1/bills/{billId}
bill.holdReleased.v1Bill event: hold released.getBillGET /v1/bills/{billId}
bill.paymentApplied.v1Bill event: payment applied.getBillGET /v1/bills/{billId}
bill.paymentReturned.v1Bill event: payment returned.getBillGET /v1/bills/{billId}
bill.submitted.v1Bill event: submitted.getBillGET /v1/bills/{billId}
bill.voided.v1Bill event: voided.getBillGET /v1/bills/{billId}
job.cancelled.v1Job event: cancelled.getJobGET /v1/jobs/{jobId}
job.failed.v1Job event: failed.getJobGET /v1/jobs/{jobId}
job.succeeded.v1Job event: succeeded.getJobGET /v1/jobs/{jobId}
paymentRun.cancelled.v1Payment run event: cancelled.getPaymentRunGET /v1/payment-runs/{runId}
paymentRun.paymentReversed.v1Payment run event: payment reversed.getPaymentRunGET /v1/payment-runs/{runId}
paymentRun.prepared.v1Payment run event: prepared.getPaymentRunGET /v1/payment-runs/{runId}
paymentRun.released.v1Payment run event: released.getPaymentRunGET /v1/payment-runs/{runId}
paymentRun.reversed.v1Payment run event: reversed.getPaymentRunGET /v1/payment-runs/{runId}
purchaseOrder.approved.v1Purchase order event: approved.getPurchaseOrderGET /v1/purchase-orders/{purchaseOrderId}
purchaseOrder.cancelled.v1Purchase order event: cancelled.getPurchaseOrderGET /v1/purchase-orders/{purchaseOrderId}
purchaseOrder.sent.v1Purchase order event: sent.getPurchaseOrderGET /v1/purchase-orders/{purchaseOrderId}
vendor.accepted.v1Vendor event: accepted.getVendorGET /v1/vendors/{vendorId}
vendor.archived.v1Vendor event: archived.getVendorGET /v1/vendors/{vendorId}
vendor.bankingChangeProposed.v1Vendor event: banking change proposed.getVendorGET /v1/vendors/{vendorId}
vendor.bankingVerified.v1Vendor event: banking verified.getVendorGET /v1/vendors/{vendorId}
vendor.created.v1Vendor event: created.getVendorGET /v1/vendors/{vendorId}
vendor.paymentHeld.v1Vendor event: payment held.getVendorGET /v1/vendors/{vendorId}
vendor.paymentHoldReleased.v1Vendor event: payment hold released.getVendorGET /v1/vendors/{vendorId}
vendor.restored.v1Vendor event: restored.getVendorGET /v1/vendors/{vendorId}
vendor.updated.v1Vendor event: updated.getVendorGET /v1/vendors/{vendorId}
vendorCredit.applied.v1Vendor credit event: applied.getVendorCreditGET /v1/vendor-credits/{vendorCreditId}
vendorCredit.approved.v1Vendor credit event: approved.getVendorCreditGET /v1/vendor-credits/{vendorCreditId}

Wire it into your books.

Book a demo and we show you the events on a working ledger.