Developer Resources
Webhooks
8min
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 { "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" } 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 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 , 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