Webhooks

Use this guide to configure and handle webhook notifications. Treat each notification as a signal to refresh workflow state, not as the source of truth.

Before you configure

You need:

• A public HTTPS endpoint (no self-signed TLS certificates).
• Separate base URLs for Sandbox and Production.
• Authentication for requests sent by Fourthline (Bearer authentication recommended).
• Validation of incoming webhook requests.
• A webhook handler that calls Get workflow status after you acknowledge the webhook.
• Idempotent processing (duplicate and out-of-order deliveries are normal).

Ask your Fourthline delivery manager to register URLs and authentication. Allow time for configuration before you rely on webhooks in Production.

---

About webhooks

Fourthline sends webhook notifications when a product status changes. Use them to trigger a workflow state refresh. Before making business decisions, call Get workflow status to retrieve the current workflow status.

Do not approve, reject, or download reports based on the webhook payload alone.

Configure one callback URL per environment. Fourthline sends POST requests with Content-Type: application/json.

The request body is a single JSON object. Properties with a null value are omitted. Route the notification by details.name: IdentityVerification, Payments (Bank Account Verification), or Signatures (Qualified Electronic Signature).

Delivery timing

We send webhook notifications shortly after a product status changes. Delivery time depends on processing time and on whether the status change was triggered automatically or manually.

Retries

If delivery fails and Fourthline does not receive an acknowledgement, we retry about once per hour for up to 5 days, unless your endpoint returns an HTTP 4xx response.

If retries continue to fail, Fourthline logs the failed notification.

Webhook notifications are not guaranteed to be delivered in order. The same event may be delivered more than once.

Idempotency: Persist or queue each event, then return 2xx before heavy work. Deduplicate using a stable key such as workflowId + details.name + details.status + timestamp (or your own event id if you add one server-side). Ignore duplicates that do not change stored state.

Missed webhooks: Run a periodic reconciliation job that calls Get workflow status for workflows still in new or pending in your database, especially after outages or repeated 4xx responses from your endpoint.

---

Set up webhooks

To set up webhooks, contact your Fourthline delivery manager, and follow these steps:

1. Register webhook URLs

• URLs must be in https format.
• We do not support self-signed certificates.
• Provide separate URLs for your Sandbox and Production environments.
• Fourthline appends workflowId path parameter to your registered base URL (the workflow UUID from Create workflow).

Example:

Note

A single webhook endpoint receives events for all workflow products. Use details.name to identify the product associated with each event.

---

2. Specify the authentication method

Specify how Fourthline authenticates when calling your webhook. We recommend Bearer authentication.

Bearer authentication

We adhere to OAuth 2.0 RFC 6750 and support token-based authentication using the Client Credentials grant.

Provide:

• A URL where we can request an access token: AuthUrl. If not provided, we use basic authentication.
• client_id and client_secret for your Sandbox and Production environments.

More information

See RFC 6750: OAuth 2.0 Bearer Token Usage and RFC 2617: HTTP Authentication – Basic and Digest Access Authentication.

Basic authentication

Before requesting webhook configuration:

• Provide the credentials used to authenticate requests to your API.
• Provide usernames and passwords for your Sandbox and Production environments.
• Email us to request the IP addresses to allow in the environments where you are configuring your webhook.

---

3. Handle webhook notifications

Fourthline starts sending notifications after configuration completes. You can register URLs early and enable your webhook handler when it is ready.

Your endpoint should:

• Accept POST only on the registered path.
• Read Content-Type: application/json and parse the request body as a single JSON object.
• Match the workflowId in the URL path to the workflowId in the body.
• Validate the inbound Authorization header (Bearer or Basic, per your setup).
• Return HTTP 2xx (typically 200) with an empty response body after you que or persist the webhook payload, not after all downstream jobs finish.
• Call Get workflow status with your Fourthline API token before you update UI or back-office state.

Product-specific behavior

• Payments: When details.status is completed, the webhook payload may include transferData (IBAN, transfer reference, amount, and related fields). Other statuses do not include transferData.
• Signatures: Statuses such as user_consent_required, confirmation_required, and signed indicate which QES API to call next. See Qualified Electronic Signature Integration. details.errorAttempts lists each error attempt with attemptId and timestamp. Read the status code from Get workflow status in products[].messages[], and match attemptId. details.messages[] includes statusCode and does not include attemptId.
• IdentityVerification: Use details.status and details.messages as indicators only. details.hash is the MD5 (lowercase hex) of the ZIP report. It is present after the report is generated and absent otherwise. details.sla is included when processing has finished, including when details.status is inconsistent_data, and omitted while the workflow is still in progress, for example pending. Confirm the outcome by calling Get workflow status and retrieving the workflow reports.
• flowVariant: Returned on the event, next to workflowId, when the workflow offers both eID and verification with a physical ID document. When the workflow does not offer both, the property is absent. eIDVerification means the client completed eID. DocumentVerification means the client completed verification with a physical ID document. Get workflow status and Get report as JSON return the same value. Confirm the webhook value with Get workflow status. PDF and XML reports do not include flowVariant.

For example webhook payloads, see the Webhooks API reference.