Connect

Webhook Format and Processing

Connect Webhooks service is a logical extension of our Messages Services. When Customer has subscribed to any of the Message types via Subscription services our system will start sending the POST requests to the host and uri configured.

Our Webhook messages contain similar data already covered in Messages Services - request and response ID's, message type, creation time etc. No business information is provided at this point and customer must use the Messages Services to read the actual Message content.

The main benefit of using Webhooks for the customer is significantly improving how the general integration is built. With Webhooks there is no need to constantly poll GET /messags endpoints to detect any new Messages pending. This is especially important for services that are not directly triggered by the customer requests like Transaction Notification. This improves both the speed of getting the newest events from the system and also reduces the load from both Client and Server side.

Subscription services are described at Managing Webhook Configurations

Sample of a typical Webhook message:

{
    "eventId": "7c334869-9c9e-43e7-b11a-be8f605f44fd",
    "eventTimestamp": "2024-08-19T07:41:18.421145632+01:00",
    "subscriptionReference": "9ab35ca0-2f58-4578-aea2-0e611f686ca9",
    "messageResponseId": "RESfaf42325221c4ba3a162286aaf76d00c",
    "messageRequestId": "REQce11219c581840199ca1e4cca0edbd17",
    "messageType": "ACCOUNT_BALANCE",
    "messageCreatedTime": "2024-08-19T07:41:18.404298+01:00",
    "regCode": "13180211",
    "regCodeIssuer": "GB",
    "bankCode": "LHVUK"
}

You can then retrieve the message body using Get message by response ID

When you have processed the message, you should mark it is processed ( Mark message as processed) just the same as if you were not using webhooks

If a webhook fails to send, we will retry it 3 times before giving up. This means that network issues could occasionally lead to webhooks never arriving or arriving more than once.

This means you should still periodically poll ( Get list of messages) to check for missed messages

See the next section for how to handle duplicates.

  • Successful request means that POST Webhook request got 2xx or 3xx HTTP response from Customers service

  • Failed requests are timeouts, 4xx or 5xx HTTP responses and any other errors.

Preventing Duplicate Processing

As discussed above, it is possible to receive the same webhook event twice. This can occur if the network connection breaks, or you return an error code, but you have already processed it.

We include the eventId field to allow you to uniquely identify a webhook event. It will be the same on any retries, meaning you can discard the message if you've seen it before (in other words, eventId is an idempotency key).

Doing this will also prevent replay attacks, where an attacker maliciously sends a webhook that was legitimately signed by us in the past.

As keeping an ever-growing set of all eventIds ever seen is not practical, you can expire old entries from your cache after a day, and similarly reject any webhook whose eventTimestamp is older than this.

Webhooks & Source IP Addresses

Webhooks are sent from a fixed LHV IP address range. Currently the list is shared for Production and Prelive Environments. Please make sure this IP range is added to your systems IP Access List.

Actual IP list will be provided by our implementation or support team!

Webhook Event Payload Schema

PreviousWebhooksNextManaging Webhook Configurations

Last updated