Lightning payment notifications for zap recipients #158
Description
Summary
When someone zaps a DID, the recipient currently has no way to know they received a payment. Drawbridge should subscribe to LNbits payment webhooks so it can notify recipients of incoming zaps.
Motivation
With the Lightning zap feature (PR #155), senders can zap any published DID. But recipients only see the payment if they check their LNbits wallet directly. A notification system would close the loop and make zaps useful for real interactions.
Proposed approach
1. Webhook registration
When Drawbridge creates an invoice via LNbits (on GET /invoice/:did), it should register a webhook URL for that invoice. LNbits supports webhook callbacks on invoice settlement.
2. Webhook handler
New endpoint on Drawbridge to receive LNbits payment callbacks:
POST /api/v1/lightning/webhook (called by LNbits)
When invoked, store a notification in Redis keyed by recipient DID:
- Payment hash
- Amount (sats)
- Memo (if provided by sender)
- Payer identity (if provided)
- Timestamp
3. Notification retrieval
Authenticated endpoint for DID owners to fetch their payment notifications:
GET /api/v1/lightning/notifications
Returns list of recent payments received, with option to mark as read / acknowledge.
4. CLI integration
keymaster lightning-notifications [id] — List incoming zap notifications
Considerations
- LNbits webhook URL must be reachable from LNbits — works naturally in Docker since both are on the same network
- Redis TTL on notifications to prevent unbounded growth
- Batch/pagination for high-volume recipients
- Could eventually support real-time push (WebSocket or SSE) in addition to polling
Related
- PR feat: Lightning zap — send sats to a DID #155 — Lightning zap via Tor (adds the zap flow this builds on)