Events#

Every event has an id (evt_…), a type (company.created, sales_invoice.created, bank_transaction.booked, …), the apiVersion it was written in, the company, and a snapshot of the object in data.object. Read the catalogue with platformEventCatalog; entries with status planned are not sent yet. An event of a module that is hidden or off for the company is not published.

platformEvents(after: <sequence>) returns events in order; store the last sequence and continue from it after downtime. Events are kept for 30 days.

Webhook endpoints#

const endpoint = await finbaze.platform.webhookEndpoints.create({ url: "https://example.com/finbaze", eventTypes: ["company.created", "bank_transaction.booked"] });
// endpoint.signingSecret is shown once

Each delivery is a POST with X-FinBaze-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">. Verify it with finbaze.webhooks.constructPlatformEvent(rawBody, header, secret); dedupe on the event id.

• Retries after a failure with growing delays (30 seconds up to 24 hours, 8 attempts). A 410 Gone disables the endpoint at once; an endpoint that keeps failing is disabled with a reason and a notice. failoverUrl is tried when the main URL fails.
• Rotation. rotatePlatformWebhookSecret returns a new secret; for keepPreviousHours the old one signs as well (the header carries two v1 values), so you can deploy the new secret without losing a delivery. Pass [new, old] to constructPlatformEvent while both are live.
• Replay. replayPlatformWebhookDelivery, replayPlatformWebhookDeliveries (by filter, rate limited) and resendPlatformEvent send an event again, marked X-FinBaze-Replay.
• pingPlatformWebhookEndpoint sends a test event.

Order and duplicates#

Webhooks are at-least-once and not ordered across events. Use sequence to order, and the event id to dedupe.