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.
{
"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"
}
}idis the event’s own identifier. Keep it: a delivery can arrive twice, and the sameidis the same event.positionis the event’s place in the ledger’s log.data.hrefis the path to read the record, on the API address. Read it with your key to get the current state.typeends 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.
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.
webhook-id: evt_cmabc123
webhook-timestamp: 1792195200
webhook-signature: v1,Ud7Yyos7Fdjc683AxYjsPGi5ShlzB9laX8UFVDNY0lU=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.
| After attempt | Wait before the next |
|---|---|
| 1 | 1 minute |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 6 hours |
| 6 | 12 hours |
| 7 | 1 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.
| Event | What happened | Read the record with |
|---|---|---|
bill.approved.v1 | Bill event: approved. | getBillGET /v1/bills/{billId} |
bill.declined.v1 | Bill event: declined. | getBillGET /v1/bills/{billId} |
bill.drafted.v1 | Bill event: drafted. | getBillGET /v1/bills/{billId} |
bill.held.v1 | Bill event: held. | getBillGET /v1/bills/{billId} |
bill.holdReleased.v1 | Bill event: hold released. | getBillGET /v1/bills/{billId} |
bill.paymentApplied.v1 | Bill event: payment applied. | getBillGET /v1/bills/{billId} |
bill.paymentReturned.v1 | Bill event: payment returned. | getBillGET /v1/bills/{billId} |
bill.submitted.v1 | Bill event: submitted. | getBillGET /v1/bills/{billId} |
bill.voided.v1 | Bill event: voided. | getBillGET /v1/bills/{billId} |
job.cancelled.v1 | Job event: cancelled. | getJobGET /v1/jobs/{jobId} |
job.failed.v1 | Job event: failed. | getJobGET /v1/jobs/{jobId} |
job.succeeded.v1 | Job event: succeeded. | getJobGET /v1/jobs/{jobId} |
paymentRun.cancelled.v1 | Payment run event: cancelled. | getPaymentRunGET /v1/payment-runs/{runId} |
paymentRun.paymentReversed.v1 | Payment run event: payment reversed. | getPaymentRunGET /v1/payment-runs/{runId} |
paymentRun.prepared.v1 | Payment run event: prepared. | getPaymentRunGET /v1/payment-runs/{runId} |
paymentRun.released.v1 | Payment run event: released. | getPaymentRunGET /v1/payment-runs/{runId} |
paymentRun.reversed.v1 | Payment run event: reversed. | getPaymentRunGET /v1/payment-runs/{runId} |
purchaseOrder.approved.v1 | Purchase order event: approved. | getPurchaseOrderGET /v1/purchase-orders/{purchaseOrderId} |
purchaseOrder.cancelled.v1 | Purchase order event: cancelled. | getPurchaseOrderGET /v1/purchase-orders/{purchaseOrderId} |
purchaseOrder.sent.v1 | Purchase order event: sent. | getPurchaseOrderGET /v1/purchase-orders/{purchaseOrderId} |
vendor.accepted.v1 | Vendor event: accepted. | getVendorGET /v1/vendors/{vendorId} |
vendor.archived.v1 | Vendor event: archived. | getVendorGET /v1/vendors/{vendorId} |
vendor.bankingChangeProposed.v1 | Vendor event: banking change proposed. | getVendorGET /v1/vendors/{vendorId} |
vendor.bankingVerified.v1 | Vendor event: banking verified. | getVendorGET /v1/vendors/{vendorId} |
vendor.created.v1 | Vendor event: created. | getVendorGET /v1/vendors/{vendorId} |
vendor.paymentHeld.v1 | Vendor event: payment held. | getVendorGET /v1/vendors/{vendorId} |
vendor.paymentHoldReleased.v1 | Vendor event: payment hold released. | getVendorGET /v1/vendors/{vendorId} |
vendor.restored.v1 | Vendor event: restored. | getVendorGET /v1/vendors/{vendorId} |
vendor.updated.v1 | Vendor event: updated. | getVendorGET /v1/vendors/{vendorId} |
vendorCredit.applied.v1 | Vendor credit event: applied. | getVendorCreditGET /v1/vendor-credits/{vendorCreditId} |
vendorCredit.approved.v1 | Vendor 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.