Webhook notifications

The sidecar can send webhook notifications when payments are finalized (completed or failed). This is useful for tracking payment status without polling.

Set LEXE_WEBHOOK_URL in your environment or pass --webhook-url to the sidecar binary:

# Via environment variable
$ export LEXE_WEBHOOK_URL="https://example.com/webhooks/lexe"

# Via CLI argument
$ lexe-sidecar --webhook-url https://example.com/webhooks/lexe

When a payment is finalized, the sidecar will POST a JSON payload to your webhook URL:

{
  "user_pk": "63ad1661bfc23ad25f5bcc6f610f8fd70d7426de51be74766c24e47f4b4fcfca",
  "index": "0000001744926519917-ln_9be5e4e3a0356cc4a7a1dce5a4af39e2896b7eb7b007ec6ca8c2f8434f21a63a",
  "rail": "invoice",
  "kind": "invoice",
  "direction": "inbound",
  "hash": "9be5e4e3a0356cc4a7a1dce5a4af39e2896b7eb7b007ec6ca8c2f8434f21a63a",
  "preimage": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
  "offer_id": null,
  "txid": null,
  "amount": "1000",
  "fees": "0",
  "partner_pk": null,
  "partner_prop_fee": null,
  "partner_base_fee": null,
  "status": "completed",
  "status_msg": "completed",
  "address": null,
  "invoice": "lnbc10n1p5qz7z2dq...",
  "tx": null,
  "payer_name": null,
  "message": null,
  "personal_note": null,
  "priority": null,
  "expires_at": 1744930119917,
  "finalized_at": 1744926857989,
  "created_at": 1744926519917,
  "updated_at": 1744926857989
}

The webhook payload uses the same response schema as GET /v2/node/payment, with an additional user_pk field to identify the wallet (useful for multi-wallet setups).

Your endpoint should return a 200 status code to indicate success.

NOTE: Make sure only the sidecar can make requests to your webhook URL! Otherwise, someone could trick your server into thinking a payment was finalized by sending a fake webhook to it. We recommend running your webhook endpoint on the same machine as the sidecar, so notifications can be received via localhost.

NOTE: All webhook handling must be idempotent. In rare occasions, you might receive a payment notification more than once.

The sidecar persists webhook tracking state to tracked_payments.json in a .lexe/ subdirectory of the current working directory. Override this directory using the LEXE_DATA_DIR environment variable or --data-dir CLI argument:

# Via environment variable
$ export LEXE_DATA_DIR="$HOME/.lexe"

# Via CLI argument
$ lexe-sidecar --data-dir ~/.lexe