Managing Webhook Configurations

A webhook configuration has the following schema:

Field
Type
Description

subscriptionReference

String

A unique ID for the webhook configuration. This is generated by us and returned from PUT requests. You can then use it to edit or delete the config

eventType

String

The type of webhook. At the moment, this should always be GENERAL_WEBHOOK

messageType

String

requestUrl

String

(URL)

The URL that we will POST the webhook events to

active

Boolean

An on/off switch for the configuration. When this is false, we will ignore this config and not send webhooks

sharedSecret

String

The HMAC shared secret. See Webhook Security. This is only shown in the response when creating or deleting configs, not when listing via GET

attachMetadata

Boolean

A boolean flag that specifies whether metadata should be included in the webhook payload. When set to true, the webhook message will include key contextual variables about the message content. See Webhook Metadata

attachFullBody

Boolean

A boolean flag that determines whether the full message content should be included in the webhook payload. When set to true, the webhook message will contain the full message encoded in Base64.

removeAfterDelivery

Boolean

A boolean flag that specifies whether messages should be removed from the response of Get next message. When set to true, messages that are successfully delivered via webhook will be automatically marked as processed. As a result, such messages will no longer appear in the Get next message service.

Example:

{
  "subscriptionReference": "3dcfe476-2dac-4239-bb42-6ca9e6613d18",
  "eventType": "GENERAL_WEBHOOK",
  "messageType": "VIBAN_OPEN",
  "requestUrl": "https://example.org",
  "active": true,
  "sharedSecret": "lsM1tyLl70I6R3TXGTlnsStLygTwCJSDz3hQMvETNZptwzFnJHWdcXOkM+JAhXFy",
  "attachMetadata": true,
  "attachFullBody": false,
  "removeAfterDelivery": false
}

requestUrl must be an https:// URL (with a valid TLS cert). It must use a domain name which is resolving properly (via an A/AAAA record) at time of registration. If you are having trouble with this and have registered the domain (or updated its records) very recently, try waiting several minutes for DNS propagation.

In our implementation every message type must be configured with a subscription separately - meaning all message are not included by default. It allows customers to subscribe to only these messages that are expected. Typically customers would want to subscribe to messages that are not directly created with a request like Transaction Notifications - Transaction Notification

You can have multiple configurations with the same URL, allowing you to have one handler for several message types. You will need to create each one with a separate PUT, and each will have its own subscriptionReference.

You can only have one configuration for a given messageType. Attempts to create duplicates will result in an error (even if one of them has active set to false).

Creating a Webhook Configuration

POST https://connect.lhv.com/notifications/subscription

This creates a new webhook configuration. The request body should be a partial webhook configuration JSON.

You must include messageType, requestUrl, and active. You can optionally include sharedSecret, or leave it absent to allow one to be generated (see Webhook Security for more info). You can also optionally include attachMetada and/or attachFullBody,these will default to false if not included.

The response will be the completed configuration, with all fields present.

Example request:

{
  "messageType": "VIBAN_OPEN",
  "requestUrl": "https://example.org",
  "active": "true",
  "attachFullBody": true
}

Example response:

{
  "subscriptionReference": "3dcfe476-2dac-4239-bb42-6ca9e6613d18",
  "eventType": "GENERAL_WEBHOOK",
  "messageType": "VIBAN_OPEN",
  "requestUrl": "https://example.org",
  "active": true,
  "sharedSecret": "emUKy3eVlmsdkEL3jMIhH/CTytlTz1F+LAhs92puGA6P6XuJkkd/J4yFScPPlLcS",
  "attachMetadata": false,
  "attachFullBody": true,
  "removeAfterDelivery": false
}

Listing Configs

GET https://connect.lhv.com/notifications/subscription

This lists your registered webhook configs, as a JSON array of config objects (without secrets).

Example response:

[
  {
    "subscriptionReference": "039ec930-a46f-42a6-8d49-5875c742b18d",
    "eventType": "GENERAL_WEBHOOK",
    "messageType": "VIBAN_CLOSE",
    "requestUrl": "https://example.org",
    "active": false,
    "attachMetadata": true,
    "attachFullBody": false,
    "removeAfterDelivery": true
  },
  {
    "subscriptionReference": "3dcfe476-2dac-4239-bb42-6ca9e6613d18",
    "eventType": "GENERAL_WEBHOOK",
    "messageType": "VIBAN_OPEN",
    "requestUrl": "https://example.org",
    "active": true,
    "attachMetadata": false,
    "attachFullBody": false,
    "removeAfterDelivery": false
  }
]

Querying a Config by Reference

GET https://connect.lhv.com/notifications/subscription/{subscriptionReference}

Example response:

{
  "subscriptionReference": "3dcfe476-2dac-4239-bb42-6ca9e6613d18",
  "eventType": "GENERAL_WEBHOOK",
  "messageType": "VIBAN_OPEN",
  "requestUrl": "https://example.org",
  "active": true,
  "attachMetadata": false,
  "attachFullBody": false,
  "removeAfterDelivery": false
}

Editing a Config

PUT https://connect.lhv.com/notifications/subscription/{subscriptionReference}

The request body should be the fields you want to edit. The webhook to edit is identified by the subscriptionReference in the body

Example request:

{
  "messageType": "VIBAN_OPEN",
  "requestUrl": "https://example.org",
  "active": "false",
  "attachMetadata": false,
  "attachFullBody": false
}

Example response:

{
  "subscriptionReference": "3dcfe476-2dac-4239-bb42-6ca9e6613d18",
  "eventType": "GENERAL_WEBHOOK",
  "messageType": "VIBAN_OPEN",
  "requestUrl": "https://example.org",
  "active": false,
  "sharedSecret": "WeLFLvveJthZ9Dr2tGJptbtvNhbt4OqLjZ6ECU5YCp/SlFh9P08GEOJ4mDuO5bNT",
  "attachMetadata": false,
  "attachFullBody": false,
  "removeAfterDelivery": false
}

Deleting a Config

DELETE https://connect.lhv.com/notifications/subscription/{subscriptionReference}

No request body is needed. The response will also have no body, just a 200 OK status to indicate success

Last updated

Was this helpful?