Skip to content

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.

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

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=***). urlHasSecret is true as 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).

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.

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): v1 is HMAC-SHA256 over <t>.<body>, where t is 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.

  • 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). cursor is the event number up to which everything matching was delivered, pendingEvents counts 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.

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.

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.

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.