Webhooks
If the leading system is reachable from fineelik, it does not have to poll. fineelik reports every event with an HTTPS POST. They are the same events as in the feed (GET /api/integration/events). A webhook is only the trigger: the receiver fetches the data afterwards with GET /api/invoices/{id}/export.
Setting up
Section titled “Setting up”Webhooks are managed by a signed-in person under Settings, Integrations: create and change needs the right settings.manage, read needs settings.read. API keys can neither see nor create webhooks.
| Field | Meaning |
|---|---|
url |
Target, https:// only, no credentials in the address (up to 500 characters). A token in the query part is allowed (ELO Flows, see below) and appears outwardly only masked. |
eventTypes |
At least one of invoice.received, invoice.status_changed, invoice.export_changed, invoice.processing_failed |
companyId |
One company (must be within your own access), or empty: all companies the creator sees at that moment. Delivery only covers what the creator still sees at delivery time. |
description |
Free text, up to 200 characters |
active |
Pause and resume. A webhook never switches itself off. |
secret |
Only when creating, optional: a secret you provide (24 to 200 characters, for example the one stored in ELO Flows). Without it fineelik creates one. |
The secret (created by fineelik: whsec_ and 32 random bytes) appears exactly once, in the answer to creating or to “rotate secret”. It is stored encrypted and never shown again. After rotating, only the new one is valid.
The management routes are listed in Reference: webhooks. They need a signed-in session, not an API key.
| Call | Effect |
|---|---|
GET /api/webhooks |
list with masked address and state (cursor, pendingEvents, lastDeliveryAt, lastDeliveryOk, lastError, failingSince) |
POST /api/webhooks |
create (201, the answer contains secret) |
PATCH /api/webhooks/{id} |
change. An address containing *** (the masked form) is rejected with 400 webhook.url_masked. |
DELETE /api/webhooks/{id} |
delete with its log; the answer is the list afterwards |
POST /api/webhooks/{id}/rotate-secret |
new secret (200, { secret }); empty body: fineelik creates it, { "secret": "..." }: yours |
POST /api/webhooks/{id}/test |
test call with immediate result (ok, statusCode, error, durationMs); one running test per webhook and 6 per minute, otherwise 429 webhook.test_throttled |
GET /api/webhooks/{id}/deliveries?limit=&offset= |
delivery log, newest first, with total; entries are kept 30 days |
Address with a token (ELO Flows)
Section titled “Address with a token (ELO Flows)”ELO Flows cannot verify the signature X-Fineelik-Signature (Flows gives triggers no headers) and secures its webhook input with a token in the address, for example https://<elo>/<path>/webhook?token=<token>. Treat the token like a secret:
- The address is stored in full and delivered in full, token included.
- Every answer, history, log and error text shows only the masked form: values of query parameters and a fragment become
***, names stay (https://elo.example.test/flows?token=***&x=***).urlHasSecretistrueas soon as the address has query parameters or a fragment. - To change it, enter the address in full again.
ELO Flows also checks a WebSub signature (X-Hub-Signature) if a secret is entered in Flows. For that you can provide the secret yourself when creating or rotating: enter the same one in Flows and in fineelik (at least 24 characters).
The delivery
Section titled “The delivery”fineelik sends a POST. The body is the event in the same form as an entry of the feed:
{ "id": "1842", "type": "invoice.status_changed", "occurredAt": "2026-09-28T10:15:02.113Z", "invoiceId": "<uuid>", "companyId": "<uuid>", "companyCode": "<company code>", "dmsGuid": "<guid in the document system or null>", "status": "approved", "previousStatus": "approval_pending", "statusReason": null}| Header | Content |
|---|---|
X-Fineelik-Signature |
t=<unix seconds>,v1=<hex> |
X-Hub-Signature |
sha256=<hex> (WebSub format, for ELO Flows) |
X-Fineelik-Event |
the event type (ping for a test call) |
X-Fineelik-Delivery |
id of this delivery attempt (appears in the log) |
User-Agent |
fineelik-webhooks/1 |
Content-Type |
application/json |
Any 2xx status counts as delivered. Everything else counts as failed: another status, a redirect (3xx; fineelik follows none), no answer within 10 seconds, a connection or certificate error. The answer body is neither read nor stored: answer with 2xx at once and do the work afterwards.
Verifying the signature
Section titled “Verifying the signature”fineelik sends both signatures with the same secret. The receiver checks one of them. The key is the secret exactly as shown or provided, including whsec_ if present (UTF-8). body is the raw request body, byte for byte, before any JSON parsing. Compare in constant time.
X-Fineelik-Signature(recommended, with a timestamp against replay):v1is HMAC-SHA256 over<t>.<body>, wheretis the value from the header. Reject timestamps more than 5 minutes away from your own clock.X-Hub-Signature(WebSub, checked by ELO Flows itself):sha256=and HMAC-SHA256 over<body>, without a timestamp. Against replay use the event number (id).
Mac mac = Mac.getInstance("HmacSHA256");mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));byte[] expected = mac.doFinal((t + "." + rawBody).getBytes(StandardCharsets.UTF_8));boolean ok = MessageDigest.isEqual(toHex(expected).getBytes(StandardCharsets.US_ASCII), v1.getBytes(StandardCharsets.US_ASCII)) && Math.abs(nowSeconds - t) <= 300;Check value: secret whsec_testgeheimnis, t = 1700000000, body {"id":"42","type":"invoice.status_changed"} gives v1=d5f4a33b0c6510fdb99e15e5aa059c51cea8869e2fe7407b161a3e4c1d58f7df and X-Hub-Signature: sha256=21e78171381c266463b9c9ad85f8d0a92d55f7480ce503feb72ed982db8239c4.
Order and retries
Section titled “Order and retries”- Delivery is in order per webhook (ascending
id). If a delivery fails, the webhook stays at this event and tries again after 1, 5, 15 and 60 minutes, then every 6 hours. The settings show “Failing since” and the last error. - A successful test call, a changed address or resuming after a pause trigger the next attempt at once.
- Delivery is at least once: after an interruption the same event can arrive a second time. Recognize it by
id. - fineelik checks for new events every 15 seconds, so an event usually arrives within about 15 seconds. In rare cases, when an earlier event is still being written, delivery waits up to 60 seconds so that the order is kept.
- A new webhook starts at the current end. It does not deliver the past (use the feed for that).
cursoris the event number up to which everything matching was delivered,pendingEventscounts what still waits. - Changes apply at once. A webhook is read freshly just before each delivery. If it is deleted, paused or changed during a delivery, that delivery stops after the running call.
Who sees what
Section titled “Who sees what”Only what the creator sees now is delivered. If a company is withdrawn from the creator, its events no longer go out. Creating, changing, pausing, rotating the secret, testing and deleting a webhook need the right settings.manage (Administrator). Everyone with settings.read can see the list and the log. If nothing is left, the creator’s account is deactivated or deleted, or the right invoices.read is missing, the webhook delivers nothing: lastError is then webhook.creator_no_access. If access returns, the next cycle delivers the events since then. Otherwise create the webhook again with an account that has access.
Test call
Section titled “Test call”A test call has the same form with type ping, id "0", the invoiceId 00000000-0000-0000-0000-000000000000 and the company of the webhook (the zero UUID if it has no fixed company). It changes neither cursor nor failure count and appears in the log. Receivers should acknowledge unknown types with 2xx and ignore them.
Allowed targets
Section titled “Allowed targets”fineelik delivers only to public addresses. Before every delivery the name is resolved and each address is checked. Blocked are private ranges (10/8, 172.16/12, 192.168/16), loopback (127/8, ::1), link-local (169.254/16, fe80::/10, including cloud metadata services), ULA (fc00::/7), carrier-grade NAT (100.64/10), multicast, unspecified and reserved addresses, also IPv4 wrapped in IPv6 and IP literals in the address. The connection then goes exactly to the checked addresses, without a second resolution. A blocked or unresolvable target gives the same text, “Target not allowed or not reachable”.
If your ELO runs in the same internal network as fineelik, contact eelik support: internal targets can be allowed for instances that a single customer runs in its own network.