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 JSON array of events (one or more objects per request). Route each event based on 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 an array.
• Match the workflowId in the URL path to the workflowId in each webhook event.
• 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.
• IdentityVerification: Use details.status and details.messages as indicators only. Confirm the outcome by calling Get workflow status and retrieving the workflow reports.

For example webhook payloads, see the Webhooks API reference.