docs: add webhook documentation

BoltzExchange · Jul 22, 2024 · f37091f · f37091f
1 parent a12561f
commit f37091f
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 6 deletions.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -10,6 +10,7 @@
 * [🚫 Don't trust. Verify!](dont-trust-verify.md)
 * [⏩ 0-conf](0-conf.md)
 * [⚠️ Common Mistakes](common-mistakes.md)
+* [🪝 Webhooks](webhooks.md)
 * [🚢 Backend Deployment](deployment.md)
 * [🐳 Regtest Environment](regtest.md)
 * [🔙 Back to Docs Home](https://app.gitbook.com/o/SPM8mTvJyc7OIzGL3HD7/s/XUXMXrD8YTzvuqvAeom7/)
diff --git a/docs/webhooks.md b/docs/webhooks.md
@@ -0,0 +1,39 @@
+---
+description: >-
+  Get notified about swap status updates
+---
+
+# 🪝 Webhooks
+
+To get the latest status of your swaps, you can poll the status endpoints of the REST API, subscribe to the WebSocket,
+or set a webhook when creating the swap.
+
+To register a webhook add the following object to the request that creates the swap:
+
+```json
+{
+  ...
+  "webhook": {
+    "url": "<URL that should called>",
+    "hashSwapId": false
+  }
+}
+```
+
+`url` will be called on every swap status update with a JSON object structured like this:
+
+```json
+{
+  "event": "swap.update",
+  "data": {
+    "id": "<swap id>",
+    "status": "<new status of the swap>"
+  }
+}
+```
+
+Only HTTPS URLs are allowed for webhooks.
+`hashSwapId` is optional and defaults to false.
+When it is explicitly set to `true`, the swap id is hashed with SHA256 and encoded as HEX in the webhook call.
+That is useful when the webhook is processed by a third party to which you do not want to leak information about your
+swaps.
diff --git a/lib/api/v2/routers/SwapRouter.ts b/lib/api/v2/routers/SwapRouter.ts
@@ -141,6 +141,23 @@ class SwapRouter extends RouterBase {
      */
     router.get('/submarine', this.handleError(this.getSubmarine));
 
+    /**
+     * @openapi
+     * components:
+     *   schemas:
+     *     WebhookData:
+     *       type: object
+     *       properties:
+     *         url:
+     *           type: string
+     *           required: true
+     *           description: URL that should be called. Only HTTPS is allowed
+     *         hashSwapId:
+     *           type: boolean
+     *           default: false
+     *           description: If the swap id in the Webhook calls should be hashed with SHA256; useful when Webhooks are processed by a third party
+     */
+
     /**
      * @openapi
      * components:
@@ -172,6 +189,8 @@ class SwapRouter extends RouterBase {
      *         referralId:
      *           type: string
      *           description: Referral ID to be used for the Submarine swap
+     *         webhook:
+     *           $ref: '#/components/schemas/WebhookData'
      */
 
     /**
@@ -457,7 +476,7 @@ class SwapRouter extends RouterBase {
      *         pubNonce:
      *           type: string
      *           required: true
-     *           description: Public nonce  encoded as HEX
+     *           description: Public nonce encoded as HEX
      *         partialSignature:
      *           type: string
      *           required: true
@@ -502,7 +521,7 @@ class SwapRouter extends RouterBase {
       this.handleError(this.signUtxoRefund(this.service.musigSigner)),
     );
 
-    // Deprecated endpoint from first Taproot deployment
+    // Deprecated endpoint from first the Taproot deployment
     router.post(
       '/submarine/refund',
       this.handleError(this.signUtxoRefund(this.service.musigSigner)),
@@ -737,7 +756,9 @@ class SwapRouter extends RouterBase {
      *           description: If the claim covenant should be added to the Taproot tree. Only possible when "address" is set
      *         description:
      *           type: string
-     *           description: Description of the created invoice and magic routing hint. Only ASCII and a maximum length of 40 characters is allowed.
+     *           description: Description of the created invoice and magic routing hint. Only ASCII and a maximum length of 40 characters is allowed
+     *         webhook:
+     *           $ref: '#/components/schemas/WebhookData'
      */
     /**
      * @openapi
@@ -917,7 +938,7 @@ class SwapRouter extends RouterBase {
      */
     router.post('/reverse/:id/claim', this.handleError(this.claimReverse));
 
-    // Deprecated endpoint from first Taproot deployment
+    // Deprecated endpoint from the first Taproot deployment
     router.post('/reverse/claim', this.handleError(this.claimReverse));
 
     /**
@@ -1091,6 +1112,8 @@ class SwapRouter extends RouterBase {
      *         referralId:
      *           type: string
      *           description: Referral ID to be used for the Chain Swap
+     *         webhook:
+     *           $ref: '#/components/schemas/WebhookData'
      */
 
     /**

diff --git a/swagger-spec.json b/swagger-spec.json
@@ -1963,6 +1963,21 @@
           }
         }
       },
+      "WebhookData": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "required": true,
+            "description": "URL that should be called. Only HTTPS is allowed"
+          },
+          "hashSwapId": {
+            "type": "boolean",
+            "default": false,
+            "description": "If the swap id in the Webhook calls should be hashed with SHA256; useful when Webhooks are processed by a third party"
+          }
+        }
+      },
       "SubmarineRequest": {
         "type": "object",
         "properties": {
@@ -1996,6 +2011,9 @@
           "referralId": {
             "type": "string",
             "description": "Referral ID to be used for the Submarine swap"
+          },
+          "webhook": {
+            "$ref": "#/components/schemas/WebhookData"
           }
         }
       },
@@ -2095,7 +2113,7 @@
           "pubNonce": {
             "type": "string",
             "required": true,
-            "description": "Public nonce  encoded as HEX"
+            "description": "Public nonce encoded as HEX"
           },
           "partialSignature": {
             "type": "string",
@@ -2241,7 +2259,10 @@
           },
           "description": {
             "type": "string",
-            "description": "Description of the created invoice and magic routing hint. Only ASCII and a maximum length of 40 characters is allowed."
+            "description": "Description of the created invoice and magic routing hint. Only ASCII and a maximum length of 40 characters is allowed"
+          },
+          "webhook": {
+            "$ref": "#/components/schemas/WebhookData"
           }
         }
       },
@@ -2447,6 +2468,9 @@
           "referralId": {
             "type": "string",
             "description": "Referral ID to be used for the Chain Swap"
+          },
+          "webhook": {
+            "$ref": "#/components/schemas/WebhookData"
           }
         }
       },