Withdrawals Webhooks

When initiating a Lightning Network withdrawal, you can register a webhook URL (via callback_url parameter). The webhook URL will notify you if your payment succeeded or failed to reach its destination.

Withdrawals status

  • status = confirmed - Lightning Transaction is settled
  • status = error - Lightning Transaction failed. Check error value for more information.
POST callback_url | application/x-www-form-urlencoded
    id: id,
    type: 'ln',
    amount: amount,
    reference: reference, // LN payment request
    processed_at: processed_at,
    address: address, // LN node's pubkey destination
    fee: fee,
    status: status, // confirmed or failed
    error: error, // if status = failed
    hashed_order: hashed_order

OpenNode signs all 'withdrawals' events it sends with a 'hashed_order' field on the event payload before we send the event to your endpoint. This validates that the events were sent by OpenNode and not a third party.

You can verify the signatures by computing an HMAC with the SHA256 hash function. Use the 'api-key' used on the 'withdrawal' creation as the key, and the 'withdrawal' id as the message.

const crypto = require('crypto');

const received = withdrawal.hashed_order;
const calculated = crypto.createHmac('sha256', MY_API_KEY).update(withdrawal.id).digest('hex');

if (received === calculated) {
    //Signature is valid
else {
    //Signature is invalid. Ignore.