Merge pull request #4 from Fewsats/verify-webhok

Verify webhook

Author: aserven

fewsats/__init__.py

@@ -1 +1 @@
-__version__ = "0.0.19"
+__version__ = "0.0.20"

fewsats/_modidx.py

@@ -23,6 +23,8 @@
                               'fewsats.core.Fewsats.pay_offer_str': ('core.html#fewsats.pay_offer_str', 'fewsats/core.py'),
                               'fewsats.core.Fewsats.payment_info': ('core.html#fewsats.payment_info', 'fewsats/core.py'),
                               'fewsats.core.Fewsats.payment_methods': ('core.html#fewsats.payment_methods', 'fewsats/core.py'),
+                              'fewsats.core.Fewsats.verify_webhook': ('core.html#fewsats.verify_webhook', 'fewsats/core.py'),
+                              'fewsats.core.FewsatsWebhookEvent': ('core.html#fewsatswebhookevent', 'fewsats/core.py'),
                               'fewsats.core.L402Offers': ('core.html#l402offers', 'fewsats/core.py'),
                               'fewsats.core.L402Offers.__init__': ('core.html#l402offers.__init__', 'fewsats/core.py'),
                               'fewsats.core.L402Offers.__repr__': ('core.html#l402offers.__repr__', 'fewsats/core.py'),

fewsats/core.py

@@ -3,20 +3,27 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_core.ipynb.
 
 # %% auto 0
-__all__ = ['Fewsats', 'Offer', 'L402Offers']
+__all__ = ['Fewsats', 'FewsatsWebhookEvent', 'Offer', 'L402Offers']
 
 # %% ../nbs/00_core.ipynb 3
 from fastcore.utils import *
 import os
+import hashlib
+import hmac
 import httpx
-from typing import Dict, Any, List
+import time
 import json
+from dataclasses import dataclass
 from fastcore.basics import BasicRepr
 from fastcore.utils import store_attr
 from typing import List, Dict, Any
 
 # %% ../nbs/00_core.ipynb 8
 class Fewsats:
+
+    WEBHOOK_VERSION = "v1"
+    WEBHOOK_SIGNATURE_HEADER = "Fewsats-Signature"
+
     "Client for interacting with the Fewsats API"
     def __init__(self,
                  api_key: str = None, # The API key for the Fewsats account
@@ -114,6 +121,63 @@ def add_webhook(self:Fewsats,
     return self._request("POST", f"v0/users/webhook/add", json={"webhook_url": webhook_url})
 
 # %% ../nbs/00_core.ipynb 39
+@dataclass
+class FewsatsWebhookEvent:
+    offer_id: str
+    payment_context_token: str
+    amount: int
+    currency: str
+    status: str
+    timestamp: str
+
+@patch(cls_method=True)
+def verify_webhook(cls:Fewsats,
+                   data: bytes,
+                   signature: str,
+                   webhook_secret: str,
+                   ) -> dict:
+    """
+    Verify and parse a webhook that comes from Fewsats
+    Args:
+        data: bytes
+        signature: str
+        webhook_secret: str
+    Returns:
+        FewsatsWebhookEvent
+    """
+    if not isinstance(data, bytes):
+        raise TypeError(f"'data' should be bytes, got {type(data)}")
+
+    timestamp_str, signature_str = signature.split(",")
+    timestamp = timestamp_str.split("=")[1]
+    signature_version, signature = signature_str.split("=")
+
+    payload_str = data.decode("utf-8")
+
+    if signature_version != cls.WEBHOOK_VERSION:
+        raise ValueError("Unsupported signature version")
+
+    if timestamp.isdigit():
+        timestamp = int(timestamp)
+    else:
+        raise ValueError("Invalid timestamp")
+
+    if timestamp - time.time() > 300:
+        raise ValueError("Timestamp is older than 5 minutes")
+
+    signed_payload = f"{timestamp}.{payload_str}"
+
+    # Generate the signature
+    expected_signature = hmac.new(webhook_secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
+
+    if signature.lower() != expected_signature.lower():
+        raise ValueError("Webhook message hash does not match signature")
+
+    event = json.loads(payload_str)
+    return FewsatsWebhookEvent(**event)
+
+
+# %% ../nbs/00_core.ipynb 42
 @patch
 def pay_lightning(self: Fewsats, 
                   invoice: str, # lightning invoice
@@ -129,7 +193,7 @@ def pay_lightning(self: Fewsats,
     }
     return self._request("POST", "v0/l402/purchases/lightning", json=data)
 
-# %% ../nbs/00_core.ipynb 42
+# %% ../nbs/00_core.ipynb 45
 class Offer(BasicRepr):
     "Represents a single L402 offer"
     def __init__(self, 
@@ -184,7 +248,7 @@ def from_dict(cls, d: Dict[str, Any]) -> 'L402Offers':
         )
 
 
-# %% ../nbs/00_core.ipynb 46
+# %% ../nbs/00_core.ipynb 49
 @patch
 def pay_offer(self:Fewsats,
         offer_id : str, # the offer id to pay for
@@ -213,7 +277,7 @@ def pay_offer(self:Fewsats,
     return self._request("POST", "v0/l402/purchases/from-offer", json=data)
 
 
-# %% ../nbs/00_core.ipynb 49
+# %% ../nbs/00_core.ipynb 52
 @patch
 def pay_offer_str(self:Fewsats,
         offer_id : str, # the offer id to pay for
@@ -250,7 +314,7 @@ def pay_offer_str(self:Fewsats,
 
     return self._request("POST", "v0/l402/purchases/from-offer", timeout=20, json=data)
 
-# %% ../nbs/00_core.ipynb 52
+# %% ../nbs/00_core.ipynb 55
 @patch
 def pay_link(self:Fewsats,
         url: str, # URL to purchase from
@@ -280,14 +344,14 @@ def pay_link(self:Fewsats,
     }
     return self._request("POST", "v0/l402/purchases/from-link", json=data)
 
-# %% ../nbs/00_core.ipynb 55
+# %% ../nbs/00_core.ipynb 58
 @patch
 def payment_info(self:Fewsats,
                   pid:str): # purchase id
     "Retrieve the details of a payment."
     return self._request("GET", f"v0/l402/outgoing-payments/{pid}")
 
-# %% ../nbs/00_core.ipynb 58
+# %% ../nbs/00_core.ipynb 61
 @patch
 def as_tools(self:Fewsats):
     "Return list of available tools for AI agents"

nbs/00_core.ipynb

@@ -34,9 +34,12 @@
     "#| export\n",
     "from fastcore.utils import *\n",
     "import os\n",
+    "import hashlib\n",
+    "import hmac\n",
     "import httpx\n",
-    "from typing import Dict, Any, List\n",
+    "import time\n",
     "import json\n",
+    "from dataclasses import dataclass\n",
     "from fastcore.basics import BasicRepr\n",
     "from fastcore.utils import store_attr\n",
     "from typing import List, Dict, Any"
@@ -94,6 +97,10 @@
    "source": [
     "#| export\n",
     "class Fewsats:\n",
+    "\n",
+    "    WEBHOOK_VERSION = \"v1\"\n",
+    "    WEBHOOK_SIGNATURE_HEADER = \"Fewsats-Signature\"\n",
+    "\n",
     "    \"Client for interacting with the Fewsats API\"\n",
     "    def __init__(self,\n",
     "                 api_key: str = None, # The API key for the Fewsats account\n",
@@ -224,7 +231,7 @@
        "  'phone': None})"
       ]
      },
-     "execution_count": 47,
+     "execution_count": null,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -552,7 +559,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Set webhook\n",
+    "## Webhooks\n",
     "\n",
     "Use this as a vendor to get notified when someone pays for your offer. Currently only 1 webhook is supported per user."
    ]
@@ -596,6 +603,108 @@
     "r, r.json()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To verify and parse a webhook that comes from Fewsats you can use this utility"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "\n",
+    "@dataclass\n",
+    "class FewsatsWebhookEvent:\n",
+    "    offer_id: str\n",
+    "    payment_context_token: str\n",
+    "    amount: int\n",
+    "    currency: str\n",
+    "    status: str\n",
+    "    timestamp: str\n",
+    "\n",
+    "@patch(cls_method=True)\n",
+    "def verify_webhook(cls:Fewsats,\n",
+    "                   data: bytes,\n",
+    "                   signature: str,\n",
+    "                   webhook_secret: str,\n",
+    "                   ) -> dict:\n",
+    "    \"\"\"\n",
+    "    Verify and parse a webhook that comes from Fewsats\n",
+    "    Args:\n",
+    "        data: bytes\n",
+    "        signature: str\n",
+    "        webhook_secret: str\n",
+    "    Returns:\n",
+    "        FewsatsWebhookEvent\n",
+    "    \"\"\"\n",
+    "    if not isinstance(data, bytes):\n",
+    "        raise TypeError(f\"'data' should be bytes, got {type(data)}\")\n",
+    "\n",
+    "    timestamp_str, signature_str = signature.split(\",\")\n",
+    "    timestamp = timestamp_str.split(\"=\")[1]\n",
+    "    signature_version, signature = signature_str.split(\"=\")\n",
+    "\n",
+    "    payload_str = data.decode(\"utf-8\")\n",
+    "\n",
+    "    if signature_version != cls.WEBHOOK_VERSION:\n",
+    "        raise ValueError(\"Unsupported signature version\")\n",
+    "\n",
+    "    if timestamp.isdigit():\n",
+    "        timestamp = int(timestamp)\n",
+    "    else:\n",
+    "        raise ValueError(\"Invalid timestamp\")\n",
+    "\n",
+    "    if timestamp - time.time() > 300:\n",
+    "        raise ValueError(\"Timestamp is older than 5 minutes\")\n",
+    "\n",
+    "    signed_payload = f\"{timestamp}.{payload_str}\"\n",
+    "\n",
+    "    # Generate the signature\n",
+    "    expected_signature = hmac.new(webhook_secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()\n",
+    "\n",
+    "    if signature.lower() != expected_signature.lower():\n",
+    "        raise ValueError(\"Webhook message hash does not match signature\")\n",
+    "\n",
+    "    event = json.loads(payload_str)\n",
+    "    return FewsatsWebhookEvent(**event)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "FewsatsWebhookEvent(offer_id='offer-501040', payment_context_token='a0b1caf3-3e3b-488f-ae9c-18d64f690894', amount=812319, currency='USD', status='failed', timestamp='2025-04-16T08:51:12Z')"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "data = bytes(json.dumps({\n",
+    "  \"offer_id\": \"offer-501040\",\n",
+    "  \"payment_context_token\": \"a0b1caf3-3e3b-488f-ae9c-18d64f690894\",\n",
+    "  \"amount\": 812319,\n",
+    "  \"currency\": \"USD\",\n",
+    "  \"status\": \"failed\",\n",
+    "  \"timestamp\": \"2025-04-16T08:51:12Z\"\n",
+    "}, sort_keys=True, separators=(',', ':')), \"utf-8\")\n",
+    "signature = \"t=1744793472,v1=89a491b8f3f8e72b75896faa24cb1cfade27bea12bbdfe333759809b8a573ad3\"\n",
+    "\n",
+    "event = Fewsats.verify_webhook(data, signature, \"whsec_bIi4m3by9sJ_KNfY5PFWb2YmAqm2WVAvwq5wGuphayE\")\n",
+    "event"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

settings.ini

@@ -1,7 +1,7 @@
 [DEFAULT]
 repo = fewsats-python
 lib_name = fewsats
-version = 0.0.19
+version = 0.0.20
 min_python = 3.7
 license = apache2
 black_formatting = False