Webhooks

Integrations guide

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:


Setup

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

1. Provide URLs

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

ProductWebhook URL
Identity Verification
Client Authentication
Document Authentication
Same URL, e.g.:
https://mysite.com/api/fourthline/idv/{verificationId}
Qualified Electronic SignatureUnique URL, e.g.:
https://mysite.com/api/fourthline/qes/{signatureId}
Bank Account VerificationUnique URL, e.g.:
https://mysite.com/api/fourthline/bav/{paymentId}
AML Screening & MonitoringUnique URL, e.g.:
https://mysite.com/api/fourthline/aml

Note
All Fourthline SDKs use the same webhook URLs.


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
Note
More information
See DataTracker – Client Credentials Grant.

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.
Note
More information
See DataTracker – Basic Authentication Scheme.


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.

Success
Success
You have configured and set up your webhooks!

Top of page