Webhooks

This page explains how to set up webhooks. For detailed information about webhook notifications, see the following references:

---

About webhooks

Fourthline uses webhooks to inform you about workflow events, such as status changes. After receiving a webhook notification, make the relevant GET status request to retrieve detailed information about the event or case.

Webhook notifications are more efficient than polling the API with GET status requests. However, they contain less information than GET status responses and are not intended to replace them.

Delivery timing

We send notifications almost immediately, depending on processing time and whether status changes were triggered automatically or manually.

Method

Fourthline webhooks use the POST method and the payload is contained in the JSON request body.

Retries

If webhook delivery fails and Fourthline does not receive an acknowledgement, we retry the notification 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.

---

Set up webhooks

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

1. Provide webhook URLs

• URLs must be in https format.
• We do not support self-signed certificates.
• You need to provide separate URLs for your Sandbox and Production environments.
• Fourthline appends an identifier for the specific instance to the URL:
  • Identity Verification: verificationId (same as the workflowId)
  • Qualified Electronic Signature: signatureId (same as the workflowId)
  • Bank Account Verification: paymentId (same as the workflowId)
  • AML Screening & Monitoring: verificationId
  • Biometric Authentication and Document Authentication: verificationId

Provide the URL per product you want us to send webhooks to:

Note

All Fourthline SDKs use the same webhook URLs.

---

2. Specify the authentication method

Specify the authentication method per product for webhook notifications sent to your server. We recommend bearer authentication.

Bearer authentication

We adhere to OAuth 2.0 RFC 6750 and support token-based authentication using the Client Credentials grant. Clients authenticate by sending their credentials through the HTTP Basic Authentication scheme.

Provide:

• A URL where we can request an access token to authenticate in your API: AuthUrl. If not provided, we use basic authentication.
• Usernames and passwords per product for your Sandbox and Production environments

More information

For more details, refer to the following IETF specifications:

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

Basic authentication

Before requesting us to set up your webhook, make sure you enable your credentials:

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

More information

See DataTracker – Basic Authentication Scheme.

---

3. Handle webhook notifications

Fourthline starts sending webhook notifications after configuration is completed.

Configure your endpoint to start receiving webhook notifications. If necessary, you can request us to set up the webhook on our side during implementation and configure it on your side later, and recover missed notifications.

However, Fourthline recommends configuring your endpoint before webhook delivery starts.

We expect that your implementation:

• Returns error responses only for actual processing failures
• Solves error responses like HTTP 401 or HTTP 403 during the integration process
• Queues webhook notifications for asynchronous processing
• Is idempotent and can handle double notifications
• Acknowledges notifications with an HTTP 200 response with no additional headers or body parameters

For what each HTTP status means when your endpoint responds to Fourthline, and how to troubleshoot 401, 403, 404, and 500.

---

Handle webhook deliveries

Fourthline calls your webhook URL and expects your server to return an HTTP status code. Delivery is accepted on the basis of the status code; an empty JSON body ({}) or no body is sufficient for success.

The API reference lists the status codes your endpoint may return. Use the tabs below to troubleshoot each response.

---

Retrieve status information

Make GET status requests per solution/module as follows:

• Identity Verification
• Get signature status
• Bank Account Verification
• Biometric Authentication
• Document Authentication