Integrations

Finpilo can send validated documents directly to your accounting system using webhooks. Instead of exporting files manually, the document data is pushed automatically when you click Send on a validated document.

This page covers how to configure webhooks at the workspace and entity level.

How webhooks work

A webhook is a URL in your accounting system that accepts incoming document data as JSON. When you click Send on a validated document in Finpilo, the following happens:

1. Finpilo builds a JSON payload with all document data — header fields, line items, dimensions, and a URL to download the original file.
2. Finpilo makes an HTTP POST to your webhook URL with this payload.
3. Your accounting system receives the data, creates a record in its database, and optionally returns an accounting reference ID in the response.
4. If the reference ID is returned, Finpilo stores it on the document and displays it in the document header.

The original file is not embedded in the webhook payload. Instead, the payload contains a fileUrl field pointing to the Finpilo file download endpoint. Your system can fetch the file using the same API key if needed.

See External API for the full webhook payload format.

Webhook resolution order

Finpilo checks two levels of webhook configuration when sending a document:

1. Entity webhook — if the entity has a custom webhook enabled with a URL, it is used.
2. Workspace webhook — if the entity has no custom webhook, the workspace-level webhook is used.

If neither is configured, the Send button is hidden entirely on the document view. You cannot send documents from an entity or workspace without a webhook.

Important exception: If an entity has "Use custom outbound webhook" enabled but no URL is set, document sending fails with an explicit error — it does not silently fall back to the workspace webhook. This is by design, to prevent sending documents to the wrong system.

Configuring the workspace webhook

Admin or Owner role required.

The workspace webhook is the default for all entities that do not have their own.

1. Navigate to Workspace Settings → API tab.
2. In the Workspace Webhook section, enter the Webhook URL — the address of your accounting system's webhook endpoint.
3. If your webhook requires authentication, enter an API Key. Finpilo sends this as a Bearer token in the Authorization header on every request.
4. Toggle Webhook enabled on.
5. Click Save.

The API Key field is always empty when you open the page. Leave it blank to keep the existing key, or enter a new value to replace it.

Configuring an entity webhook

Admin or Owner role required.

Use an entity-level webhook when a specific entity needs to send to a different accounting system than the rest of the workspace.

1. Navigate to Entity Management and click on the entity.
2. Select the Integrations tab.
3. Turn on the Use custom outbound webhook toggle.
4. Enter the Webhook URL.
5. If authentication is required, enter an API Key.
6. Turn on the Webhook enabled toggle below to activate sending.
7. Click Save.

Turning off Use custom outbound webhook and saving reverts the entity to using the workspace webhook. Turning it off without saving discards any unsaved changes.

Testing the webhook

The simplest way to test a webhook is to validate a document and click Send:

• If the send succeeds, the document status changes to Sent and a timestamp appears in the header.
• If the send fails, an error message appears. Common errors:
  • The webhook URL returned an HTTP error.
  • The request timed out (Finpilo waits 30 seconds for a response).
  • No webhook is configured or the entity webhook is enabled without a URL.

Accounting reference ID

If your webhook endpoint returns a JSON body containing one of the fields accountingReferenceId, AccountingReferenceId, or id, Finpilo stores that value on the document as a back-reference to the record in your accounting system.

Example webhook response:

{
  "accountingReferenceId": "INV-2026-0042"
}

The reference ID is displayed in the document header as Ref: INV-2026-0042. This makes it easy to locate the corresponding record in the external system.

Returning an accounting reference ID is optional. An empty 200 OK response is also valid.

Security

• API keys are encrypted at rest.
• The full webhook API key is never displayed after saving — only a masked placeholder appears.
• Webhook requests are always sent over HTTPS. Configure your endpoint with a valid HTTPS certificate.