This page sets out how to set up webhooks.

About webhooks

Fourthline uses webhooks to notify you about events in your workflows, e.g. status changes.
When you receive a webhook notification, make the relevant GET status request to receive detailed information about the event or case.

Webhooks are more efficient than polling our server with GET status requests to check if events have occurred. However, they contain less information than GET status responses and aren’t intended to replace them.

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.

GET status requests

Make GET status requests per solution/module as follows:

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

---

Setup

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

1. Provide URLs

• URLs must be in https format.
• We don't support self-signed certificates.
• You need to provide separate URLs for your sandbox and production environments.
• For the following solutions, we append our identifier for the specific instance at the end of the URL, which you need to handle:
  • 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: None
  • Client Authentication and Document Authentication: verificationId

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

---

2. Specify authentication method

To send webhook notifications to your server, specify per product if you want to use bearer authentication (recommended) or basic authentication.

Bearer authentication

We support token-based authentication by client credentials grant, sending the client credentials you provided using 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

Basic authentication

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

• Provide us an access token to authenticate in your API: UserId.
• 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.

---

3. Consume webhooks

On our side, we implement webhooks as soon as you request them.

On your side, set up your implementation to consume webhooks when you want to start receiving 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, we don't recommend this option.

We expect that your implementation:

• Only throws an error when it is down
• Solves error responses like HTTP 401 or HTTP 403 during the integration process
• Is resilient and queues receiving messages on your side for successful notifications
• Is idempotent and can handle double notifications
• Acknowledges notifications with an HTTP 200 response with no additional headers or body parameters

Retries

If a notification fails for any reason and we don't receive your acknowledgement and the HTTP status code isn't in the 4XX range, we try to resend the notification once per hour for 5 days.

If we still get no acknowledgement, we just log the notification.

Top of page