Webhooks

voltage webhooks give you real time visibility and automation capabilities for your lightning nodes and voltage infrastructure with just a few configuration steps, you can subscribe to critical events from your infrastructure—ranging from invoice settlements and channel state changes to new block notifications and wallet unlock requests these webhooks are built to be reliable, secure, and developer friendly each webhook includes rich metadata, automatic retry behavior, and support for custom event handling so your stack can respond immediately and intelligently to activity on your node lightning node webhooks custom voltage hosted invoice webhook implementation reach out to have the voltage hosted invoice webhook activated for your team readme # webhook proxy documentation \## overview the webhook proxy service allows you to receive real time notifications from your lnd nodes via webhooks it supports multiple event types and provides reliable delivery with automatic retries \## webhook payload when an event occurs, the service will send a post request to your configured webhook url with the following payload structure ```json { "node id" "string", // the id of the lnd node that generated the event "event type" "string", // type of event (see event types below) "data" { // event specific data }, "metadata" { "timestamp" 1708387874, // unix timestamp of when the event was sent "attempt" 1, // current delivery attempt number "max retries" 3, // maximum number of retry attempts "webhook id" "string", // id of your webhook configuration "delivery id" "string" // unique id for this delivery attempt } } ``` \### http headers each webhook request includes the following headers ``` content type application/json x event type \<event type> x node id \<node id> x webhook id \<webhook id> x delivery id \<delivery id> x attempt \<current attempt> x max retries \<max retries> ``` \## event types the service supports the following event types \### 1 invoice events (`event type "invoice"`) triggered when an invoice is created, settled, or canceled ```json { "event type" "invoice", "data" { "payment hash" "string", "value sat" "integer", "settled" "boolean", "creation date" "integer", "settle date" "integer", "payment request" "string", "memo" "string", "state" "string" // "open", "settled", or "canceled" } } ``` \### 2 channel events (`event type "channel"`) triggered for channel related events (open, close, pending, active, inactive) ```json { "event type" "channel", "data" { "channel point" "string", "capacity" "integer", "remote pubkey" "string", "channel id" "integer", "event" "string", // "open", "closed", "active", "inactive", "pending" "close type" "string" // only present for "closed" events } } ``` \### 3 block events (`event type "block"`) triggered when a new block is detected ```json { "event type" "block", "data" { "block hash" "string", "block height" "integer", "timestamp" "integer" } } ``` \### 4 transaction events (`event type "transaction"`) triggered when a new on chain transaction is detected ```json { "event type" "transaction", "data" { "tx hash" "string", "amount" "integer", "num confirmations" "integer", "block hash" "string", "block height" "integer", "timestamp" "integer", "is outbound" "boolean" } } ``` \### 5 peer events (`event type "peer"`) triggered when peers connect or disconnect ```json { "event type" "peer", "data" { "peer pubkey" "string", "address" "string", "action" "string" // "connected" or "disconnected" } } ``` \### 6 chain events (`event type "chain"`) triggered for blockchain related events ```json { "event type" "chain", "data" { "block hash" "string", "block height" "integer", "event" "string" // "reorg" or "confirmed" } } ``` \## delivery behavior \ the service will attempt to deliver webhooks immediately when events occur \ if delivery fails, it will retry with exponential backoff \ default retry configuration 3 attempts with 5 second initial delay \ successful delivery requires a 2xx response (200, 201, or 202) \ any non 2xx response is considered a failure and will trigger a retry \ each retry includes the current attempt number in both the payload and headers \## best practices 1\ idempotency always use the `delivery id` to deduplicate webhook deliveries 2\ quick response your webhook endpoint should respond quickly (< 5 seconds) 3\ async processing if you need to do heavy processing, accept the webhook quickly and process asynchronously 4\ verification store your webhook configurations securely and verify the webhook id in the headers 5\ logging use the delivery id for correlation in your logs \## error handling your webhook endpoint should handle errors gracefully 1\ return 2xx status code if you successfully received and queued/processed the webhook 2\ return 429 if you need the proxy to back off temporarily 3\ return 4xx for validation errors or if you explicitly don't want a retry 4\ return 5xx if you want the proxy to retry the delivery custom self serve invoice webhook implementation here is an example that you can fork and refactor, or deploy as a simple service independently https //replit com/@voltage cloud/lnd invoices webhook pro https //replit com/@voltage cloud/lnd invoices webhook proxy infrastructure webhooks voltage also provides webhook support for monitoring your node's lifecycle, configuration, and operational status — allowing you to build automated responses for events like node restarts, updates, or initialization these webhooks are especially useful for automatically unlocking your node after restart alerting when a new version of lnd or volt is available detecting when your node stops or enters maintenance mode each infrastructure webhook includes a standard payload structure and is delivered with the voltage secret header for verification event payload structure { "type" "string", // "status", "update", or "error" "details" { // event specific details }, "api" "string" // your node's endpoint (e g yournode m voltageapp io) } supported infrastructure event types 1\ status events type "status" these events indicate your node’s current state in the startup lifecycle or runtime waiting unlock triggered when your node restarts and is waiting to be unlocked { "type" "status", "details" { "status" "waiting unlock" }, "api" "yournode m voltageapp io" } waiting init triggered when your node is brand new and awaiting initialization { "type" "status", "details" { "status" "waiting init" }, "api" "yournode m voltageapp io" } stopped triggered when your node is gracefully or unexpectedly stopped { "type" "status", "details" { "status" "stopped" }, "api" "yournode m voltageapp io" } 2\ update events type "update" these events inform you when a new version of lnd or the voltage agent (volt) is available for your node update available { "type" "update", "details" { "update available" "true", "lnd version" "0 17 0 beta", "volt version" "v0 4 0" }, "api" "yournode m voltageapp io" } verifying infra webhooks when handling infrastructure webhooks, your server should verify the voltage secret header matches your stored secret validate the api field to ensure it matches your expected node check the type and details to confirm event purpose take appropriate action based on event type (e g , unlock the wallet, notify admin, etc) example automatically unlocking your node you can use voltage webhooks to automatically unlock your node after it restarts this is especially useful for automation or unattended node restarts step 1 set your webhook endpoint to begin, configure your webhook endpoint in the voltage dashboard navigate to your node in the voltage dashboard click monitoring in the sidebar select webhooks & watchtowers find the webhook url field and paste in the endpoint where voltage should send webhook events make note of your webhook secret – this will be required to verify incoming requests step 2 handle the waiting unlock event once your webhook is set, you’ll need to handle the waiting unlock event to trigger the unlock example payload { "type" "status", "details" { "status" "waiting unlock" }, "api" "yournode m voltageapp io" } your webhook handler should verify the voltage secret header matches your stored secret validate the api field to ensure the event came from the expected node check the type field is status check the details status field is waiting unlock if all checks pass, proceed to unlock the wallet step 3 unlock the node via lnd api to unlock the wallet, send a post request to your node's /v1/unlockwallet endpoint this follows the lnd api documentation the payload must contain wallet password your wallet password, base64 encoded stateless init set to true example curl x post https //yournode m voltageapp io 8080/v1/unlockwallet \\ d '{ "wallet password" "cgfzc3dvcmqk", "stateless init" true }' replace the wallet password value with your base64 encoded password security reminder store your webhook secret and wallet password securely using a password manager or environment variables never hard code credentials into your source code with this setup in place, your node will automatically unlock itself every time it restarts – fully automated and ready to route again replit example automatically unlocking your node