Developer documentation

Aeglio Webhooks

Receive selected business events in your own system as they happen. Every delivery is signed, versioned and retried outside your normal Aeglio workflow.

Start free trial API documentation

Quick start

Create an endpoint, then choose its events.

1Create a public HTTPS endpoint that accepts JSON POST requests.
2In Aeglio, open Settings → Developers → Webhooks and add the endpoint and events.
3Store the signing secret shown once, verify each request, and return a 2xx response.

Delivery format

Aeglio sends a JSON POST request to the configured endpoint. The body is versioned so receivers can process a known payload contract. Each event subject is identified as data.id; relationship fields such as client_id use the same IDs exposed by the API.

{
  "id": "event UUID",
  "type": "invoice.paid",
  "version": 1,
  "occurred_at": "2026-08-09T12:00:00.000000Z",
  "data": { "…": "event-specific fields" }
}

For *.updated events, data.changed_fields is a JSON array of changed field names, for example ["status", "due_date"].

Header	Purpose
X-Aeglio-Event	Event name, such as `invoice.paid`.
X-Aeglio-Event-Id	Unique event ID. Store it to make processing idempotent.
X-Aeglio-Webhook-Version	Payload version.
X-Aeglio-Timestamp	Unix timestamp included in the signature.
X-Aeglio-Signature	Signature in the form `v1=<hex digest>`.

Verify signatures

Use the exact raw request body before parsing or reformatting it. Calculate HMAC-SHA256 over the timestamp, a period, and that raw body using the endpoint signing secret.

expected = HMAC_SHA256(
  timestamp + "." + raw_request_body,
  signing_secret
)

X-Aeglio-Signature = "v1=" + expected

Compare signatures with a timing-safe comparison.
Reject requests with an old timestamp to reduce replay risk.
Store each event ID after successful processing so a retry cannot create duplicate work.

Reliability

Fast acknowledgement, safe recovery.

Any 2xx response completes a delivery. Other responses and connection failures are retried up to 5 times with increasing delays. Aeglio automatically pauses an endpoint after 10 consecutive final delivery failures, so an unhealthy receiver cannot create unbounded work.

Manage subscriptions with the API

Teams can also create, update, pause, resume and delete webhook subscriptions through the Aeglio API. Use webhooks:read to view subscriptions and delivery history, and webhooks:manage to change them.

A signing secret is returned only when creating a subscription or rotating its secret. It is never included in normal API reads.

Open the webhook API reference

Available events

Choose only the events your receiver needs. An endpoint may subscribe to events from more than one group.

Customers, suppliers and contacts

counterparty.created counterparty.updated counterparty.deleted contact.created contact.updated contact.deleted

Projects

project.created project.updated project.archived project.unarchived project.deleted

Invoices

invoice.created invoice.updated invoice.sent invoice.paid invoice.overdue invoice.refunded invoice.payment_received

Expenses

expense.created expense.updated expense.payment_received expense.paid expense.overdue expense.deleted expense.approved

Reimbursements

reimbursement.approved reimbursement.partially_paid reimbursement.paid reimbursement.reversed

Documents

document.received document.deleted document.ready_for_review document.converted document.failed

Approvals

approval.requested approval.step_advanced approval.decided approval.recalled

Accounting and integrations

accounting_export.sent accounting_export.failed integration.connected integration.disconnected integration.failed