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	The type of Connect messages that will be sent via this webhook configuration. See the types at Message Types
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
}

We will only show you the generated sharedSecret once, in the response to this request. If you lose it then you'll need to generate a new one using the edit endpoint (below)

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
}

If you want to keep using the same sharedSecret then you must provide it in the edit request body. If it is absent then a new secret will be generated and returned, replacing the old one

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