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/webhookswith an OAuth token carryingwebhooks:manage: list, subscribe and unsubscribe.
201 response carries subscription and secret (whsec_…). The secret is shown this once, so store it now.
consentAcknowledgedmust betrue. Show the person the consent text fromGET …/webhooksfirst.- 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 withfieldFilter.
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.
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
2xxwithin 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 withPATCH /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
createdAtif order matters. - Delivered and dead deliveries are kept for 30 days.
GET /api/automations/webhooks/{id}/deliverieslists recent ones, andPOST …/deliveries/{deliveryId}/redeliversends 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.
X-AI2Fin-Delivery or data.id.