Skip to main content
Webhooks send an HTTPS POST to your URL when something happens in your books, so a spreadsheet, an automation tool or your own service can follow along without polling. Webhooks are part of the Auto+ plan. The events, headers and payloads below are also published as an AsyncAPI 3.0 document, so you can generate a typed handler or validate a delivery against it.

Events

The machine-readable definitions are in the webhooks section of the OpenAPI document.

Setting up a subscription

Two ways, with the same rules behind them:
  • In the app (Settings → Automations), or with your session token at /api/automations/webhooks. This surface also pauses and resumes, rotates the secret, sends a test ping, lists deliveries and redelivers.
  • REST Hooks for automation platforms, at /api/integrations/v1/webhooks with an OAuth token carrying webhooks:manage: list, subscribe and unsubscribe.
The 201 response carries subscription and secret (whsec_…). The secret is shown this once, so store it now.
  • consentAcknowledged must be true. Show the person the consent text from GET …/webhooks first.
  • The URL must be https:// on port 443 with a DNS name. IP addresses, local or internal names, credentials in the URL, and names that resolve to private addresses are refused. The address is checked again on every delivery.
  • An account can have up to 10 subscriptions.

Payloads

Every event shares one envelope. Fields are kept to a minimum: the base fields below, plus any you opt into with fieldFilter.
fieldFilter accepts description, reference and notes; today only description appears in any event. Transactions from connected bank feeds are included and marked source: "bank_feed". ping has no apiVersion: { "event": "ping", "createdAt": "…", "data": { "message": "AI2Fin webhook test delivery" } }.

Verifying the signature

Each delivery carries these headers: Check the signature against the raw bytes of the body, before parsing it, and reject timestamps more than five minutes from your clock.
Accept the delivery if any v1= value matches. After you rotate the secret, deliveries carry two v1= values (new and previous secret) for 24 hours, so you can switch your receiver over without missing anything. A second rotation is refused until that window has closed.

Delivery and retries

  • Answer with any 2xx within 10 seconds. Anything else, or no answer, counts as a failure.
  • A failed delivery is retried after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours: six attempts in all over about seven hours. After the last it is marked dead.
  • Eight dead deliveries in a row pause the subscription (disabledReason: "auto_disabled_delivery_failures"). Resume it from Automations, or with PATCH /api/automations/webhooks/{id} and { "active": true }, which also resets the count.
  • Deliveries are queued and usually sent within about 10 seconds of the event. Order is not guaranteed; use createdAt if order matters.
  • Delivered and dead deliveries are kept for 30 days. GET /api/automations/webhooks/{id}/deliveries lists recent ones, and POST …/deliveries/{deliveryId}/redeliver sends one again (up to 7 days old, with a new delivery id).
  • Pausing or deleting a subscription stops its deliveries at once, including any still waiting.
Treat webhooks as at-least-once: the same event can arrive more than once, so make your handler safe to run twice, keyed on X-AI2Fin-Delivery or data.id.