Setting up and receiving webhooks

Fintoro sends a POST request to your URL when an event you subscribe to occurs.

Creating a subscription

Set up a subscription in Fintoro under Automatizácie → Fintoro API, or through POST /webhook-subscriptions with write permission. Choose a receiver URL and events. The API reference documents subscription management endpoints and parameters. Securely store plainTextSecret from the 201 response to verify signatures. It is not returned in subscription details. The URL must use HTTPS, resolve to a public IP address, and contain no credentials. It is validated when saving and before sending; an invalid URL ends delivery as failed.

Testing webhooks locally

We recommend a tunnel such as Cloudflare Tunnel or Expose. Set the tunnel’s public HTTPS URL in the subscription, including the receiver’s path, such as /webhooks/fintoro.

Request body

Illustrative event:

{
  "id": "7f4d1861-9f6a-4fa8-a8a7-f335d7a8d515",
  "type": "invoices.updated",
  "occurredAt": "2026-03-18T15:04:05Z",
  "resource": {
    "type": "invoice",
    "id": 301
  }
}

id identifies the event, and resource.id identifies the record in Fintoro. occurredAt is the event’s creation time in UTC. Determine the company from your subscription configuration; the body does not include it.

Headers and signature

Header	Meaning
`webhook-id`	Same value as `id` in the body.
`webhook-timestamp`	Time the current delivery attempt was sent, as a Unix timestamp in seconds.
`webhook-signature`	Hex-encoded HMAC SHA-256 of the original body bytes, using the subscription’s secret as the key.

Compare signatures in constant time. Calculate the signature over the unchanged body, without reserializing JSON. The webhook-id and webhook-timestamp headers are not signed.

Accepting and processing events

Store the verified event in a durable queue or database inbox with atomic duplicate detection using id from the body.
After storage, return 2xx, such as 204 No Content. Acknowledge an already accepted event the same way, without adding it again.
Process the event outside the HTTP request. For example, for invoices.updated with ID 301, fetch GET /invoices/301.

The API details may already include later changes than the received event. After acknowledging with 2xx, your integration is responsible for retrying subsequent processing failures.

Redelivery

Fintoro retries a non-2xx response, timeout, or network error with the same event id.

Setting	Value
Timeout per attempt	10 seconds
Attempts	Up to 5, including the initial attempt
Wait between attempts	Approximately 10 s, 100 s, 1,000 s, and 10,000 s

After all attempts are exhausted, the delivery remains failed. Delivery failure does not automatically deactivate the subscription.

Changing a subscription

Setting isActive: false stops new deliveries. Already queued attempts may still run. Changing the URL or events does not change the secret. Obtain a new one through POST /webhook-subscriptions/{id}/rotate-secret and update your receiver as well. Already queued requests may use the previous secret.

Getting started

Using the API

Webhooks

Examples