diff --git a/23.md b/23.md new file mode 100644 index 0000000..64b96cd --- /dev/null +++ b/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`.