Webhook events · FinBaze for Platforms

Reference

Generated from the event catalogue the API runs on: 126 events are available, 2 are planned (registered, not sent yet; platformEventCatalog shows the status). Concepts, retries and replay: Events and webhooks.

The envelope#

Every delivery is a POST with a JSON body:

{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "bank_transaction.booked",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankTransaction",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}

Field
`id`	`evt_…`, the event id. Dedupe on it.
`type`	The event type.
`apiVersion`	The API version the payload is written in.
`created`, `occurredAt`	When FinBaze recorded the event, and when it happened.
`sequence`	A string that grows with every event. Use it to order; gaps are normal.
`livemode`	`false` in the sandbox.
`platform`	Your platform id.
`company`	`{ id, externalId }` of the company, or `null` for platform-level events.
`request`	`{ id }` of the request that caused it, when there was one (the `X-Request-Id`).
`data.object`	A snapshot of the object as of the event, or the event's own fields.
`data.details`	Event-specific fields beside the snapshot, for events that define them.

Headers and signature#

Header
`X-FinBaze-Signature`	`t=<unix seconds>,v1=<hex>[,v1=<hex>]`: HMAC-SHA256 of `<t>.<raw body>` keyed with the endpoint's `whsec_…` secret. Two `v1` values while a secret rotates.
`X-FinBaze-Event`, `X-FinBaze-Event-Id`, `X-FinBaze-Event-Sequence`	Type, id and sequence, so you can route before parsing.
`X-FinBaze-Delivery`	The delivery id (one event can have several deliveries).
`X-FinBaze-Timestamp`	The unix timestamp used in the signature.
`X-FinBaze-Api-Version`	The API version of the payload.
`X-FinBaze-Replay`	`1` on a replayed delivery.

Accept timestamps within 5 minutes. Verification code in Node, Python and PHP: webhook receivers.

Planned events are listed so you can see what is coming; you cannot subscribe to them yet.

Companies, users and sessions #

Company lifecycle and transfers, platform users, access requests from your users, embed sessions.

Event	Status	Object
`company.archived`	available	`company`	A closed company was archived: users removed, consents revoked, retention date set.
`company.closed`	available	`company`	A company was closed: obligations end at the effective date; final returns and exports stay possible.
`company.created`	available	`company`	A company was created for the platform.
`company.features.updated`	available	`company`	The features available to a company changed (allowance or limits).
`company.reactivated`	available	`company`	A suspended company was reactivated.
`company.reopened`	available	`company`	A closed company was reopened (or an archived one restored as closed by FinBaze).
`company.requirements.updated`	available	`company`	What a company still has to provide changed (for now: its filing authorisation, `tax_*_authorisation`). `data.details.reason` says why.
`company.suspended`	available	`company`	A company was suspended (read-only; no filings, automations or outbound mail).
`company.transfer.cancelled`	available	none	A pending transfer was cancelled.
`company.transfer.created`	available	none	The company admin started a transfer to another platform or to direct FinBaze.
`company.transferred_in`	available	`company`	A company arrived from another platform. Set up its users and collect consent again.
`company.transferred_out`	available	none	A company left the platform (to another platform or to direct FinBaze). The last event the platform receives for it.
`company.updated`	available	`company`	A company's details changed.
`embed_session.used`	available	`embed_session`	An embed session was exchanged for a token.
`platform_user.created`	available	`platform_user`	A platform user was created.
`platform_user.deactivated`	available	`platform_user`	A platform user was deactivated.
`platform_user.deprovisioned`	available	`platform_user`	A platform user was deprovisioned: access removed and every token revoked.
`user.invite_requested`	available	`user_access_request`	A company admin asked, in users-and-access, to give someone access. FinBaze sends no invitation and creates no account: the platform decides.
`user.removal_requested`	available	`user_access_request`	A company admin asked to remove someone’s access. The access stays until the platform calls removePlatformUserAccess.
`user.role_change_requested`	available	`user_access_request`	A company admin asked to change a person’s role. Nothing changes until the platform calls setPlatformUserAccess.

Bookkeeping #

Invoices, quotes, relations and bank transactions.

Event	Status	Object	Module
`attachment.matched`	planned	`process_document`	`process_documents`	A document was matched to a transaction.
`bank_account.created`	available	`bank_account`	`banking`	A bank account was added to a company.
`bank_account.updated`	available	`bank_account`	`banking`	A bank account changed.
`bank_transaction.booked`	available	`bank_transaction`	`banking`	A bank transaction was booked.
`bank_transaction.created`	available	`bank_transaction`	`banking`	A bank transaction arrived (feed, file or import).
`bank_transaction.needs_receipt`	available	`bank_transaction`	`banking`	A booked transaction still needs a receipt.
`bank_transaction.needs_review`	available	`bank_transaction`	`banking`	A transaction needs a person to look at it.
`bank_transaction.unbooked`	available	`bank_transaction`	`banking`	The booking of a bank transaction was undone.
`journal_entry.created`	available	`journal_entry`	`settlements`	A journal entry was booked through the platform API.
`purchase_invoice.approved`	available	`purchase_invoice`	`purchase_invoices`	A purchase invoice was approved.
`purchase_invoice.created`	available	`purchase_invoice`	`purchase_invoices`	A purchase invoice was received or created.
`purchase_invoice.due`	available	`purchase_invoice`	`purchase_invoices`	A purchase invoice is due.
`purchase_invoice.paid`	available	`purchase_invoice`	`purchase_invoices`	A purchase invoice was paid.
`purchase_invoice.processed`	available	`purchase_invoice`	`purchase_invoices`	A purchase invoice was processed.
`quote.accepted`	available	`quote`	`quotes`	A quote was accepted.
`quote.sent`	available	`quote`	`quotes`	A quote was sent.
`relation.bank_account_changed`	available	`relation`	`relations`	The bank account of a relation changed.
`relation.created`	available	`relation`	`relations`	A relation was created.
`relation.updated`	available	`relation`	`relations`	A relation changed.
`reminder.paid`	available	`reminder`	`reminders`	A reminder was paid.
`reminder.sent`	available	`reminder`	`reminders`	A payment reminder was sent.
`sales_invoice.created`	available	`sales_invoice`	`sales_invoices`	A sales invoice was created through the platform API.
`sales_invoice.credited`	available	`sales_invoice`	`sales_invoices`	A sales invoice was credited.
`sales_invoice.finalised`	available	`sales_invoice`	`sales_invoices`	A sales invoice was numbered and booked.
`sales_invoice.overdue`	available	`sales_invoice`	`sales_invoices`	A sales invoice is overdue.
`sales_invoice.paid`	available	`sales_invoice`	`sales_invoices`	A sales invoice was paid.
`sales_invoice.sent`	available	`sales_invoice`	`sales_invoices`	A sales invoice was sent.

Data in #

Bulk jobs, data sources, feed health, records and flow runs.

Event	Status	Object	Module
`bulk_job.completed`	available	`bulk_job`		A bulk job finished.
`bulk_job.failed`	available	`bulk_job`		A bulk job failed.
`data_source_file.failed`	available	`data_source_file`		A statement file could not be processed.
`data_source_file.processed`	available	`data_source_file`		A statement file was processed.
`data_source.backfill_completed`	available	`data_source_attachment`		The history of a data source finished loading.
`data_source.resync_requested`	available	`data_source_attachment`		A person in the partner portal asked for a period of a company to be delivered again. `data.object.from` and `data.object.to` name the days; deliver them with the usual feed calls.
`feed.balance_mismatch`	available	`feed_account`	`banking`	A delivered balance does not match the transactions.
`feed.delayed`	available	`feed_account`	`banking`	A bank feed is later than usual.
`feed.gap_detected`	available	`feed_account`	`banking`	A bank feed stopped delivering.
`feed.recovered`	available	`feed_account`	`banking`	A bank feed is healthy again.
`flow_run.failed`	available	`flow_run`	`custom_records`	A flow template failed.
`flow_run.succeeded`	available	`flow_run`	`custom_records`	A flow template ran.
`record.created`	available	`custom_record`	`custom_records`	A custom record was created.
`record.transitioned`	available	`custom_record`	`custom_records`	A custom record moved to another state.
`record.updated`	available	`custom_record`	`custom_records`	A custom record changed.

Tax #

Filings, consent, payments and reservations.

Event	Status	Object	Module
`tax_authorisation.granted`	available	`tax_authorisation`	`tax_filings`	A company user authorised FinBaze to file the listed taxes (`companyId`, `taxes`, `channel`, `stepUp`, `at`). No IP or user agent.
`tax_authorisation.revoked`	available	`tax_authorisation`	`tax_filings`	A filing authorisation was revoked for the listed taxes (`channel` is how: embed, headless, platform, admin or lifecycle).
`tax_filing.accepted`	available	`tax_filing`	`tax_filings`	A tax return was accepted.
`tax_filing.draft_ready`	available	`tax_filing`	`tax_filings`	A tax return draft is ready.
`tax_filing.paid`	available	`tax_filing`	`tax_filings`	The payment of a tax return was matched.
`tax_filing.ready`	available	`tax_filing`	`tax_filings`	A tax return is ready to be submitted.
`tax_filing.rejected`	available	`tax_filing`	`tax_filings`	A tax return was rejected.
`tax_filing.submitted`	available	`tax_filing`	`tax_filings`	A tax return was submitted.
`tax_payment.due`	available	`tax_filing`	`tax_filings`	A tax payment is due.
`tax_payment.overdue`	available	`tax_filing`	`tax_filings`	A tax payment is overdue.
`tax_reservation.advised`	available	none		A new tax reservation advice was computed.
`tax_signal.created`	available	`tax_signal`	`ai.tax.signals`	A tax signal was raised.

Payroll #

Pay runs and payslips.

Event	Status	Object	Module
`pay_run.approved`	available	`pay_run`	`payroll`	A pay run was approved.
`pay_run.calculated`	available	`pay_run`	`payroll`	A pay run was calculated.
`pay_run.paid`	available	`pay_run`	`payroll`	A pay run was paid.
`payslip.finalised`	available	`payslip`	`payroll`	A payslip was finalised.

Documents and messages #

Documents and rendering, messages, exports, domains.

Event	Status	Object	Module
`custom_action.invoked`	available	none		A user invoked one of your custom actions.
`custom_domain.status_changed`	available	`custom_domain`		A custom domain for public pages changed status.
`document_request.cancelled`	available	`document_request`	`document_requests`	A document request was cancelled.
`document_request.created`	available	`document_request`	`document_requests`	A document request was created.
`document_request.fulfilled`	available	`document_request`	`document_requests`	A document request was fulfilled.
`document.failed`	available	`process_document`	`process_documents`	A document could not be processed.
`document.needs_review`	planned	`process_document`	`process_documents`	A document needs a person to look at it.
`document.official_copy_created`	available	none		The official copy of a document was stored.
`document.processed`	available	`process_document`	`process_documents`	A document was processed.
`document.received`	available	`process_document`	`process_documents`	A document was received.
`document.render_failed`	available	none		A custom template or partner render failed or timed out; FinBaze used its own layout.
`document.render_rejected`	available	none		A PDF the platform rendered failed the required-content checks; FinBaze used its own layout.
`document.render_requested`	available	none		A document needs to be rendered by the platform. The payload has the data model and signed links to files that go with it (the invoice UBL), valid 15 minutes.
`export.destination_expiring`	available	`export_destination`	`data_export`	Credentials of an export destination expire soon.
`export.failed`	available	`export_run`	`data_export`	A scheduled export failed.
`export.ready`	available	`export_run`	`data_export`	A scheduled export is ready.
`message.created`	available	none		A message needs to be delivered by the platform.
`message.unacknowledged`	available	none		A delivered message was not acknowledged in time.

Delegated actions #

Payment requests, payment links and step-up challenges.

Event	Status	Object
`payment_link.requested`	available	none	A payment link is needed for an invoice.
`payment_request.created`	available	none	A payment request was created; pay it and use the end-to-end id.
`payment_request.paid`	available	none	The bank transaction of a payment request was matched.
`payment_request.updated`	available	none	A payment request changed status.
`step_up.required`	available	none	A step-up confirmation is required for a high-risk action.

Accounting firms #

Accountant connections.

Event	Status	Object
`firm.access_requested`	available	`firm_engagement`	An accounting firm asked for access to a company. Show the request in your own UI; the company decides in accountant-connect.
`firm.authority_changed`	available	`firm_engagement`	The company changed which taxes the firm files.
`firm.connected`	available	`firm_engagement`	An accounting firm now works the company in the FinBaze firm dashboard.
`firm.connection_declined`	available	`firm_engagement`	A request between a company and a firm was declined (or withdrawn).
`firm.connection_expired`	available	`firm_engagement`	A request between a company and a firm expired after 14 days without an answer.
`firm.connection_requested`	available	`firm_engagement`	A company invited an accounting firm; the firm has not accepted yet.
`firm.disconnect_scheduled`	available	`firm_engagement`	The engagement ends at a set time because accountant access was hidden for the company; the key can still be shown again to cancel it.
`firm.disconnected`	available	`firm_engagement`	The engagement ended: firm access, BECON use and HMRC client authorisations stopped; the books stay with the company.

Support #

Support requests, escalations and consented access.

Event	Status	Object
`support.access_expired`	available	`support_access_grant`	A support grant reached its end.
`support.access_granted`	available	`support_access_grant`	A support access request was approved; FinBaze support can view the company until `expiresAt`.
`support.access_requested`	available	`support_access_grant`	FinBaze support asked to view a company. The company admin decides.
`support.access_revoked`	available	`support_access_grant`	A live support grant was ended early.
`support.break_glass`	available	`support_access_grant`	FinBaze opened a company without consent (two admins, read only, at most two hours).
`support.escalation.created`	available	`support_escalation`	An escalation to FinBaze support was created.
`support.escalation.updated`	available	`support_escalation`	An escalation changed status or severity, or got a comment.
`support.requested`	available	`support_request`	A company user asked for help in contact-support and the platform handles support (`partner_first`).

Platform: policies, quotas and agents #

Policy changes, quotas, usage reports, partner alerts and agent tasks.

Event	Status	Object	Module
`agent_task.completed`	available	`agent_task`	`ai.agents`	An agent task completed.
`agent_task.failed`	available	`agent_task`	`ai.agents`	An agent task failed.
`agent_task.waiting_approval`	available	`agent_task`	`ai.agents`	An agent task waits for approval.
`agent_task.waiting_input`	available	`agent_task`	`ai.agents`	An agent task waits for input.
`billing.usage.reported`	available	`platform_usage`		The month's usage was closed and reported.
`platform.alert`	available	`platform_alert`		Something needs the platform's attention: a failing or disabled webhook endpoint, a stalled feed, a rejected filing.
`policy.activated`	available	`platform_policy`		A policy version was activated (also by a promotion).
`quota.reached`	available	none		A company reached one of its quotas for the month.

Sandbox #

Test clocks and the sandbox reset.

Event	Status	Object
`sandbox.reset.completed`	available	`sandbox_reset`	The nightly or manual reset of the platform sandbox finished (sandbox only).
`test_clock.failed`	available	`test_clock`	A test clock stopped because the advance failed (sandbox only).
`test_clock.ready`	available	`test_clock`	A test clock finished advancing (sandbox only).