Skip to content

Reference: Webhooks

Webhooks push events to a URL of the leading system, so that it does not have to poll. They carry the same events as listIntegrationEvents. A webhook is only the trigger: the receiver reads the data afterwards as usual with getInvoiceExport.

Who manages webhooks. Signed-in users with the permission settings.manage (create, change, delete, renew the secret, send a test call) or settings.read (list, read the delivery log), in the web app under Settings, Interfaces. API keys can neither see nor create webhooks: these routes use the session cookie (SessionCookie), not x-api-key. A user sees and changes a webhook only if the user’s company access covers its whole scope.

Subscription. A webhook has a target url (https only, no credentials in the address, up to 500 characters), at least one event type, an optional description, an active switch (a webhook never switches itself off) and optionally one company. Without a company it covers all companies the creator can see at that moment. This scope is stored; what is delivered is cut to what the creator can still see at delivery time.

Secret. fineelik generates a secret (whsec_ followed by 32 random bytes) unless you pass your own when creating or renewing (24 to 200 characters, for example the one entered in ELO Flows). The secret appears exactly once, in the answer to creating or renewing. It is stored encrypted and never shown again, not in lists and not in any history. After renewing, only the new secret is valid.

Address with token (ELO Flows). ELO Flows cannot verify the signature header (Flows gives no headers to triggers) and secures its webhook input with a token in the address, for example https://<elo>/<path>/webhook?token=<token>. Such a token is a secret like the signing secret. The address is stored and delivered in full, but every answer, 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 then true. To change the address, send the complete new address. An address that contains *** is refused with 400 webhook.url_masked, so that nobody saves the masked form. ELO Flows also checks the WebSub signature (X-Hub-Signature) when a secret is set in Flows: enter the same secret (at least 24 characters) in Flows and in fineelik.

Delivery. fineelik sends an HTTPS POST for each event, with the body described in WebhookEvent. Any 2xx status counts as delivered. Everything else counts as failed: another status, a redirect (fineelik follows none), no answer within 10 seconds, a connection or certificate error. The answer body is neither read nor stored. Answer with 2xx immediately and do the work afterwards.

Order and retries. Events go out one after the other per webhook, in ascending id. When a delivery fails, the webhook stays at this event and tries again after 1, 5, 15 and 60 minutes, then every 6 hours. A successful test call, a changed address or resuming after a pause triggers the next attempt at once. Delivery is at least once: after an abort the same event can arrive twice, so recognize it by its id. An event goes out 10 seconds after it was created at the earliest, normally within 10 to 30 seconds. A new webhook starts at the current end of the event stream and does not deliver the past (use listIntegrationEvents for that). Changes to a webhook apply immediately: after a change, at most the event in flight still goes out with the old settings.

What is delivered. Only what the creator can see now. If the creator loses access to a company, its events stop. If nothing is left, the account is disabled or deleted, or the creator lacks invoices.read, the webhook delivers nothing: lastError is then webhook.creator_no_access, pendingEvents is 0, and the web app shows “no access”. When access returns, the next cycle delivers the events since then. Otherwise create the webhook again with an account that has access.

Allowed targets. fineelik delivers only to public addresses. Before every delivery the name is resolved and every address is checked; one blocked address is enough to refuse. Blocked are private (10/8, 172.16/12, 192.168/16), loopback (127/8, ::1), link-local (169.254/16, fe80::/10, which includes cloud metadata services), unique local (fc00::/7), carrier-grade NAT (100.64/10), multicast, unspecified and reserved addresses, also when wrapped as IPv4 in IPv6 and as an IP literal in the address. The connection goes to exactly the checked addresses, without a second resolution. The error text for a blocked address, an unresolvable name and an empty answer is deliberately the same, so that test calls cannot be used to probe internal names. Instances that a single customer runs in its own network can allow internal targets by operator configuration; https stays mandatory.

Audit. Creating, changing, deleting and renewing the secret are recorded in the audit log, without the secret and with the masked address.

Method Path Summary
GET /api/webhooks List webhooks
POST /api/webhooks Create a webhook
PATCH /api/webhooks/{id} Change a webhook
DELETE /api/webhooks/{id} Delete a webhook
POST /api/webhooks/{id}/rotate-secret Renew the secret of a webhook
POST /api/webhooks/{id}/test Send a test call to a webhook
GET /api/webhooks/{id}/deliveries List the delivery log of a webhook

GET /api/webhooks

Operation id: listWebhooks

Lists the webhooks that the signed-in user may see: those whose scope the user’s company access covers completely. The address is masked and each entry shows the delivery state (cursor, pendingEvents, lastDeliveryAt, lastDeliveryOk, lastError, failingSince).

Authentication: Signed-in session cookie (SessionCookie), not available to API keys

Responses

Status Meaning Body
200 The webhooks. WebhookList
401 Not signed in, or the session has ended. ApiError
403 The signed-in user lacks the permission settings.read, or the call used an API key (API keys cannot use webhook routes). ApiError

POST /api/webhooks

Operation id: createWebhook

Creates a webhook. The answer contains the signing secret, which appears only here and never again. A new webhook starts at the current end of the event stream and does not deliver past events.

Authentication: Signed-in session cookie (SessionCookie), not available to API keys

Request body (required)

Content type: application/json

Schema: CreateWebhookRequest

Responses

Status Meaning Body
201 The webhook was created. CreateWebhookResponse
400 The body is invalid, or the address is refused (webhook.url_invalid, webhook.url_not_https, webhook.url_credentials, webhook.url_masked, webhook.url_blocked), or the account has no company that a webhook could deliver for (webhook.no_company_scope). ApiError
401 Not signed in, or the session has ended. ApiError
403 The signed-in user lacks the permission settings.manage, or the call used an API key (API keys cannot use webhook routes). ApiError
404 The company does not exist or is outside the access (company.not_found). ApiError

PATCH /api/webhooks/{id}

Operation id: updateWebhook

Changes the given fields of a webhook; at least one is required. Send a changed address always complete: an address that contains *** (the masked form) is refused with 400 webhook.url_masked. Changes apply immediately.

Authentication: Signed-in session cookie (SessionCookie), not available to API keys

Parameters

Name In Type Required Description
id path string (uuid) yes Id of the webhook.

Request body (required)

Content type: application/json

Schema: UpdateWebhookRequest

Responses

Status Meaning Body
200 The changed webhook. Webhook
400 The body is invalid or the address is refused (webhook.url_invalid, webhook.url_not_https, webhook.url_credentials, webhook.url_masked, webhook.url_blocked). ApiError
401 Not signed in, or the session has ended. ApiError
403 The signed-in user lacks the permission settings.manage, or the call used an API key (API keys cannot use webhook routes). ApiError
404 The webhook does not exist or is outside the access (webhook.not_found), or the company does not exist (company.not_found). ApiError

DELETE /api/webhooks/{id}

Operation id: deleteWebhook

Deletes the webhook together with its delivery log. The answer is the list of webhooks after the deletion.

Authentication: Signed-in session cookie (SessionCookie), not available to API keys

Parameters

Name In Type Required Description
id path string (uuid) yes Id of the webhook.

Responses

Status Meaning Body
200 The webhooks that remain. WebhookList
400 The id is not a UUID. ApiError
401 Not signed in, or the session has ended. ApiError
403 The signed-in user lacks the permission settings.manage, or the call used an API key (API keys cannot use webhook routes). ApiError
404 The webhook does not exist or is outside the access (webhook.not_found). ApiError

POST /api/webhooks/{id}/rotate-secret

Operation id: rotateWebhookSecret

Creates a new signing secret. With an empty body or {} fineelik generates it, with { "secret": "..." } the given one applies. The new secret appears only in this answer. From now on only the new secret is valid.

Authentication: Signed-in session cookie (SessionCookie), not available to API keys

Parameters

Name In Type Required Description
id path string (uuid) yes Id of the webhook.

Request body

Content type: application/json

Schema: RotateWebhookSecretRequest

Responses

Status Meaning Body
200 The new secret. RotateWebhookSecretResponse
400 The body is invalid, for example a secret that is too short. ApiError
401 Not signed in, or the session has ended. ApiError
403 The signed-in user lacks the permission settings.manage, or the call used an API key (API keys cannot use webhook routes). ApiError
404 The webhook does not exist or is outside the access (webhook.not_found). ApiError

POST /api/webhooks/{id}/test

Operation id: testWebhook

Sends a ping event (see WebhookEvent) to the address and returns the result at once. A test call changes neither the cursor nor the failure count and appears in the delivery log. At most one test call runs per webhook at a time, and at most 6 per minute are accepted; beyond that the answer is 429 webhook.test_throttled. A successful test call also triggers the next delivery attempt of a failing webhook.

Authentication: Signed-in session cookie (SessionCookie), not available to API keys

Parameters

Name In Type Required Description
id path string (uuid) yes Id of the webhook.

Responses

Status Meaning Body
200 The result of the call. A failed call is also answered with 200: look at ok. WebhookTestResult
400 The secret of the webhook is not readable (webhook.secret_unreadable). Renew the secret. ApiError
401 Not signed in, or the session has ended. ApiError
403 The signed-in user lacks the permission settings.manage, or the call used an API key (API keys cannot use webhook routes). ApiError
404 The webhook does not exist or is outside the access (webhook.not_found). ApiError
429 A test call is already running, or too many were sent (webhook.test_throttled). ApiError

GET /api/webhooks/{id}/deliveries

Operation id: listWebhookDeliveries

Returns the delivery log of the webhook, newest first. Entries stay for 30 days. Entries about invoices appear only for companies within the access of the reader; test calls always appear.

Authentication: Signed-in session cookie (SessionCookie), not available to API keys

Parameters

Name In Type Required Description
id path string (uuid) yes Id of the webhook.
limit query integer no Entries per page, 1 to 100. Default 25. Default: 25. Minimum 1. Maximum 100.
offset query integer no Number of entries to skip. Default 0. Default: 0. Minimum 0. Maximum 9007199254740991.

Responses

Status Meaning Body
200 One page of the delivery log. WebhookDeliveries
400 A parameter is invalid. ApiError
401 Not signed in, or the session has ended. ApiError
403 The signed-in user lacks the permission settings.read, or the call used an API key (API keys cannot use webhook routes). ApiError
404 The webhook does not exist or is outside the access (webhook.not_found). ApiError