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 Secretas this will be used to validate the request.

When an event is triggered, Voltage will make a POSTrequest 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-Secretwhich 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-Secretheader 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.

type: the typefield 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.

Waiting for Unlock

This means the node is waiting to be unlocked.

Waiting for Initialization

This means the node is waiting to be initialized.

Stopped

This means the node just entered the Stopped state.

Update Available

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

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-Secretheader to ensure it matches what you expect. Second, you should validate the apifield 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 typefield. If the typeis statusthen you can proceed to check the details.status field. If the details.statusfield equals waiting_unlockthen 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 POSTrequest with a JSON payload containing 2 fields. wallet_passwordand stateless_init. You're password must be base64 encoded and stateless_initmust be true. Here's an example of what it would look like with curl:

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