# Managing Webhook Configurations

A webhook configuration has the following schema:

<table><thead><tr><th width="263">Field</th><th width="94">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriptionReference</code></td><td>String</td><td>A unique ID for the webhook configuration. This is generated by us and returned from <code>PUT</code> requests. You can then use it to edit or delete the config</td></tr><tr><td><code>eventType</code></td><td>String</td><td>The type of webhook. At the moment, this should always be <code>GENERAL_WEBHOOK</code></td></tr><tr><td><code>messageType</code></td><td>String</td><td>The type of Connect messages that will be sent via this webhook configuration. See the types at <a data-mention href="../../messages#message-types">#message-types</a></td></tr><tr><td><code>requestUrl</code></td><td><p>String</p><p>(URL)</p></td><td>The URL that we will <code>POST</code> the webhook events to</td></tr><tr><td><code>active</code></td><td>Boolean</td><td>An on/off switch for the configuration. When this is false, we will ignore this config and not send webhooks</td></tr><tr><td><code>sharedSecret</code></td><td>String</td><td>The HMAC shared secret. See <a data-mention href="webhook-security">webhook-security</a>. This is only shown in the response when creating or deleting configs, not when listing via <code>GET</code></td></tr><tr><td><code>attachMetadata</code></td><td>Boolean</td><td>A boolean flag that specifies whether metadata should be included in the webhook payload. When set to <code>true</code>, the webhook message will include key contextual variables about the message content. See <a data-mention href="webhook-metadata">webhook-metadata</a></td></tr><tr><td><code>attachFullBody</code></td><td>Boolean</td><td>A boolean flag that determines whether the full message content should be included in the webhook payload. When set to <code>true</code>, the webhook message will contain the full message encoded in Base64.</td></tr><tr><td><p></p><p><code>removeAfterDelivery</code></p></td><td>Boolean</td><td>A boolean flag that specifies whether messages should be removed from the response of <a data-mention href="../messages/get-next-message">get-next-message</a>. When set to <code>true</code>, messages that are successfully delivered via webhook will be automatically marked as processed. As a result, such messages will no longer appear in the <a data-mention href="../messages/get-next-message">get-next-message</a> service.</td></tr><tr><td><code>compressionEnabled</code></td><td>Boolean</td><td>A boolean flag indicating whether webhook messages should be compressed. When set to <code>true</code>, the entire payload of the webhook message will be delivered in compressed form.</td></tr></tbody></table>

Example:

```json
{
  "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
  "compressionEnabled": true 
}
```

`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](https://docs.lhv.com/home/connect/services/account-reports/transaction-notification "mention")

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

<mark style="color:green;">`POST`</mark> <https://connect.lhv.com/notifications/subscription>

{% hint style="info" %}
In a [Service Provider model](https://docs.lhv.com/home/connect/fundamentals/service-provider-model#service-provider-model), webhook configurations are managed by the Service Provider. End users do not configure webhook subscriptions directly; webhook configuration and maintenance are handled at the Service Provider level.
{% endhint %}

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](https://docs.lhv.com/home/connect/services/webhooks/webhook-security "mention") for more information). 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:

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

Example response:

```json
{
  "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
  "compressionEnabled": false 
}
```

{% hint style="warning" %}
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)
{% endhint %}

## Listing Configs

<mark style="color:green;">`GET`</mark> <https://connect.lhv.com/notifications/subscription>

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

Example response:

```json
[
  {
    "subscriptionReference": "039ec930-a46f-42a6-8d49-5875c742b18d",
    "eventType": "GENERAL_WEBHOOK",
    "messageType": "VIBAN_CLOSE",
    "requestUrl": "https://example.org",
    "active": false,
    "attachMetadata": true,
    "attachFullBody": false,
    "removeAfterDelivery": true
    "compressionEnabled": 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
    "compressionEnabled": true 
  }
]
```

## Querying a Config by Reference

<mark style="color:green;">`GET`</mark> <https://connect.lhv.com/notifications/subscription/{subscriptionReference}>

Example response:

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

## Editing a Config

<mark style="color:green;">`PUT`</mark> <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:

<pre class="language-json"><code class="lang-json">{
  "messageType": "VIBAN_OPEN",
<strong>  "requestUrl": "https://example.org",
</strong>  "active": "false",
  "attachMetadata": false,
  "attachFullBody": false
}
</code></pre>

Example response:

<pre class="language-json"><code class="lang-json">{
<strong>  "subscriptionReference": "3dcfe476-2dac-4239-bb42-6ca9e6613d18",
</strong>  "eventType": "GENERAL_WEBHOOK",
  "messageType": "VIBAN_OPEN",
  "requestUrl": "https://example.org",
  "active": false,
  "sharedSecret": "WeLFLvveJthZ9Dr2tGJptbtvNhbt4OqLjZ6ECU5YCp/SlFh9P08GEOJ4mDuO5bNT",
  "attachMetadata": false,
  "attachFullBody": false,
  "removeAfterDelivery": false
  "compressionEnabled": true 
}
</code></pre>

{% hint style="warning" %}
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
{% endhint %}

## Deleting a Config

<mark style="color:green;">`DELETE`</mark> <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

## Managing Connect EE webhooks

Webhooks for LHV Estonia (EE) are handled through dedicated subscription services. While standard services like Payments and Account Statements automatically route to Connect EE, their core systems are supported by LHV EE. Moreover, the features and execution of webhooks are managed by LHV EE, making these services distinct from those offered by LHV UK.

**These services can still be executed via a UK host by using the `x-bank-code=LHVEE` HTTP header**. This eliminates the need to connect directly to the EE host and issue certificates solely for this purpose.

For example:

```
// Subscribe to EE webhooks
POST https://connect.lhv.com/notifications/subscribe
-- HTTP header: x-bank-code = LHVEE
{
    "url": "https://xxxxx.webhook.office.com/xxxxxxxxx",
    "eventType": "GENERAL_WEBHOOK"
}
```

Full list of EE services: <https://partners.lhv.ee/en/connect/#webhooks>