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 |
List webhooks
Section titled “List webhooks”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 |
Create a webhook
Section titled “Create a webhook”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 |
Change a webhook
Section titled “Change a webhook”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 a webhook
Section titled “Delete a webhook”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 |
Renew the secret of a webhook
Section titled “Renew the secret of a webhook”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 |
Send a test call to a webhook
Section titled “Send a test call to a webhook”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 |
List the delivery log of a webhook
Section titled “List the delivery log of a webhook”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 |