Webhooks
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.
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.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.There are 3 root fields to the JSON payload;
type
, details
, and api
.The
type
field is used to specify what type of event it was. The current options are status
, update
, or error
.The
details
field will include specific details about the event based on the what Type the event is.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.
This means the node is waiting to be unlocked.
{
"type": "status",
"details": {
"status": "waiting_unlock"
},
"api": "yournode.m.voltageapp.io"
}
This means the node is waiting to be initialized.
{
"type": "status",
"details": {
"status": "waiting_init"
},
"api": "yournode.m.voltageapp.io"
}
This means the node just entered the Stopped state.
{
"type": "status",
"details": {
"status": "stopped"
},
"api": "yournode.m.voltageapp.io"
}
This means the node has a new update available for it.
{
"type": "update",
"details": {
"update_available": "true",
"lnd_version": "0.13.1",
"volt_version": "v0.3.1"
},
"api": "yournode.m.voltageapp.io"
}
This event is sent when we find an important error in your log messages about the order of Bitcoin blocks being out of order. If you receive this, you should restart your node as soon as you can.
{
"type": "error",
"details": {
"type": "out_of_order_block",
"log": "CRTR: out of order block: expecting height=660646, got height=660648"
},
"api": "yournode.m.voltageapp.io"
}
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 Settings. Click Connection Settings to expand the list of information and you will find your Webhook URL and Secret.

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 API directly to your node's endpoint. Following the LND API Documentation, 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 -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!
You should always use some sort of password manager or environment variables for the Voltage Webhook Secret and your node's password.
Last modified 5mo ago