From 4eb76be464d7f34b6dd925c1e4fb94896a827c11 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hampus=20Sj=C3=B6berg?= <hampus.sjoberg@protonmail.com>
Date: Wed, 16 Mar 2022 11:57:07 +0400
Subject: [PATCH] LUD-23 Webhook notification for a third-party in pay protocol

---
 23.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 23.md

diff --git a/23.md b/23.md
new file mode 100644
index 0000000..b7797fd
--- /dev/null
+++ b/23.md
@@ -0,0 +1,73 @@
+LUD-23: Webhook notification for a third-party in pay protocol.
+=================================
+
+`author: hsjoberg` `author: andreneves` `author: fiatjaf`
+
+---
+
+## Third-party webhook notification
+
+In cases where an LNURL-pay code is displayed on a third-party website,
+it could make sense to be able to give feedback to the user upon a payment
+completion.
+
+## Construction
+
+In order to accomplish this, the third party can re-construct the bech32 code or
+build a [LUD-17](./17.md) raw LNURL code, with a `webhook` query parameter
+amended to the URL. The value of `webhook` is a URL that should be called by the
+wallet upon payment completion.
+
+In the case of a [LUD-16](./16.md) Lightning Address, the query parameter `MUST`
+be added the translated URL instead of the Internet Identifier.
+
+Raw LNURL:
+`lnurlp://domain.com/pay?webhook=thirdparty.com/webhook`
+
+Bech32:
+`lnurl1dp68gurn8ghj7er0d4skjm3wvdhk6tmsv9un7am9vf5x7mmt846xs6tjv3cxzun50yhxxmmd9amk2cngdahkkxmx8qr`
+
+Translated Lightning Address:
+`lnurlp://domain.com/.well-known/lnurlp/user?webhook=thirdparty.com/webhook`
+
+## Service-side
+
+To signal support for webhook notification, the `SERVICE` `MUST` include
+property `webhookAllowed` in its first callback.
+
+```diff
+ {
+   "callback": String,
+   "maxSendable": MilliSatoshi,
+   "minSendable": MilliSatoshi,
+   "metadata": String,
++  "webhookAllowed": Boolean,
+   "tag": "payRequest",
+ }
+```
+
+If the service received `webhook` query parameter `SERVICE` `MUST` make a `POST`
+call to the `webhook` parameter URL when the invoice is settled.
+
+The body payload should be in the following format:
+
+```JSON
+ {
+   "paymentHash": String,
+   "status": "settled",
+   "amount": MilliSatoshi,
+   "preimage": String,
+ }
+```
+
+The `status` property should be of type String and be equal to `settled`.
+
+## Wallet-side
+
+Upon seeing the `webhook` query parameter in the LNURL, `WALLET` `SHOULD` inform
+the user that the third-party may will receive info about payments for this LNURL-pay code.
+
+`WALLET` `MAY` inform the user if the `webhookAllowed` response in the first
+wallet does not exist.
+
+`WALLET` `MUST` disallow payments if `webhookAllowed` is set to `false`.