---
title: Webhooks
slug: webhooks
docTags: 
createdAt: 2024-02-03T19:25:12.579Z
---

The Voltage Platform supports webhooks to notify users about events in their node. This document will explain how to use the Voltage webhooks as well as example payloads.

## Adding a Webhook Endpoint

You can add a webhook endpoint to your node by editing the node's settings. First navigate to your node and click `Expand Settings`. Once your settings are expanded, there is field named `Webhook URL`. Fill in this field with the endpoint that you'd like Voltage to make a request to. While you're in the settings you should also note down the field labeled `Webhook Secret`as this will be used to validate the request.

## How it Works

When an event is triggered, Voltage will make a `POST`request to your webhook endpoint. This request will include a JSON payload with details about the event. This request will also include a header named `Voltage-Secret`which will contain your webhook secret. When receiving the webhook event, you should parse the fields and take appropriate action.

You should always validate both the `Voltage-Secret`header and the `"api"`field in the JSON payload. This will help you ensure that the request was made from Voltage and you are sending requests to a node or endpoint that you trust.

## Payload Schema

There are 3 root fields to the JSON payload: `type`, `details`, and `api`. 

**type**: the `type`field is used to specify what type of event it was. The current options are `status`, `update`, or `error`.

**details**: The `details` field will include specific details about the event based on what the `type` the event is. 

**api**: This is the API endpoint for the node the event was sent for. This can be used to respond to the event and also validate what node the event was for. 

## Webhook Events

### Satus

**Waiting for Unlock**

 This means the node is waiting to be unlocked. 

```none
{
    "type": "status",
    "details": {
        "status": "waiting_unlock"
    },
    "api": "yournode.m.voltageapp.io"
}
```

**Waiting for Initialization**

This means the node is waiting to be initialized.

```none
{
    "type": "status",
    "details": {
        "status": "waiting_init"
    },
    "api": "yournode.m.voltageapp.io"
}
```

**Stopped**

This means the node just entered the Stopped state.

```none
{
    "type": "status",
    "details": {
        "status": "stopped"
    },
    "api": "yournode.m.voltageapp.io"
}
```

### Update

**Update Available**

This means the node has a new update available for it.

```none
{
    "type": "update",
    "details": {
        "update_available": "true",
        "lnd_version": "0.13.1",
        "volt_version": "v0.3.1"
    },
    "api": "yournode.m.voltageapp.io"
}
```

## Example Webhook - Automatic Unlock

As an example, we'll demonstrate how to automatically unlock your node whenever it's restarted. First, you must set your Webhook endpoint in your node's settings. Go to your node on the Voltage Dashboard and click Monitoring on the left side menu. Click Webhooks & Watchtowers to find your Webhookd URL field and Webhook secret. 



![](https://api.archbee.com/api/optimize/CGGF0VLgJQypTJbZ1FbQy/Ux6rrz8oP87CI4mcZL4_P_image.png)

Once you have your webhook endpoint set, now you need to handle the `waiting_unlock `status event. When a request comes in, you should first check the `Voltage-Secret`header to ensure it matches what you expect. Second, you should validate the `api`field in the JSON payload to ensure it's what you expect. If either of these are not what you're expecting, you should stop processing the event.

Once you've confirmed the secret and API fields are what you're expecting, you will check the `type`field. If the `type`is `status`then you can proceed to check the `details.status `field. If the `details.status`field equals `waiting_unlock`then you can continue processing the event and unlock your node.

Unlocking the node requires making an API call directly to your node's endpoint. Following the [LND API Documentaion](https://lightning.engineering/api-docs/api/lnd/index.html), we'll be making a call to the `/v1/unlockwallet` API. This takes a `POST`request with a JSON payload containing 2 fields. `wallet_password`and `stateless_init`. You're password must be base64 encoded and `stateless_init`must be `true`. Here's an example of what it would look like with `curl`:

```curl
curl -X POST https://yournode.m.voltageapp.io:8080/v1/unlockwallet  \
    -d '{ "wallet_password":"cGFzc3dvcmQK","stateless_init":true}'
```

Now, everytime you restart your node your webhook will automatically unlock the node for you!

:::hint{type="danger"}
You should always use some sort of password manager or environment variables for the Voltage Webhook Secret and your node's password.
:::