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.
}

Lightning errors

• timeout

  • The payment attempt failed because it didn't complete in time, often due to network delays.

• no_route

  • The payment couldn't be routed because there were no available paths with enough liquidity.

• incorrect_payment_details

  • The payment failed due to incorrect details, like a mismatched payment hash or amount.