LUD-23 Webhook notification for a third-party in pay protocol

23.md

@@ -0,0 +1,74 @@
+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
+service 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 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`.