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.

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 the what 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
Status
Waiting for Unlock
This means the node is waiting to be unlocked.
{
    "type": "status",
    "details": {
        "status": "waiting_unlock"
    },
    "api": "yournode.m.voltageapp.io"
}
Waiting for Initialization
This means the node is waiting to be initialized.
{
    "type": "status",
    "details": {
        "status": "waiting_init"
    },
    "api": "yournode.m.voltageapp.io"
}
Stopped
This means the node just entered the Stopped state.
{
    "type": "status",
    "details": {
        "status": "stopped"
    },
    "api": "yournode.m.voltageapp.io"
}
Update
Update Available
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"
}
Error
Out of Order Block Error
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"
}
​
Example - 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 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.