fix: webhook signature verification matches backend protocol

- Handle v1= prefix in signature header
- Timestamp is Unix milliseconds (not seconds)
- Add compute_signature() helper
- Rewrite tests to mirror backend's computeSignature() exactly
- Update README with correct header format and examples

Author: Shanjai

README.md

@@ -586,7 +586,14 @@ print(f"Download: {url_info.url}")
 
 ## Webhook Verification
 
-Commune signs every webhook delivery with HMAC-SHA256. Always verify before processing:
+Commune signs every outbound webhook delivery with HMAC-SHA256. The signature uses the format `v1={hex_digest}` and the timestamp is Unix **milliseconds**:
+
+```
+x-commune-signature: v1=5a3f2b...
+x-commune-timestamp: 1707667200000
+```
+
+Always verify before processing:
 
 ```python
 from commune import verify_signature, WebhookVerificationError
@@ -595,23 +602,34 @@ from commune import verify_signature, WebhookVerificationError
 try:
     verify_signature(
         payload=request.body,
-        signature=request.headers["X-Commune-Signature"],
+        signature=request.headers["x-commune-signature"],
         secret="whsec_...",  # Your inbox webhook secret
-        timestamp=request.headers.get("X-Commune-Timestamp"),
+        timestamp=request.headers["x-commune-timestamp"],
     )
 except WebhookVerificationError as e:
     print(f"Invalid webhook: {e}")
     return 401
 ```
 
+You can also compute signatures yourself (useful for testing):
+
+```python
+from commune import compute_signature
+
+sig = compute_signature(payload=body, secret="whsec_...", timestamp="1707667200000")
+# → "v1=5a3f2b..."
+```
+
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `payload` | `bytes \| str` | Yes | Raw request body |
-| `signature` | `str` | Yes | `X-Commune-Signature` header |
+| `signature` | `str` | Yes | `x-commune-signature` header (`v1=...`) |
 | `secret` | `str` | Yes | Your inbox webhook secret |
-| `timestamp` | `str` | No | `X-Commune-Timestamp` header (enables freshness check) |
+| `timestamp` | `str` | Yes* | `x-commune-timestamp` header (Unix ms) |
 | `tolerance_seconds` | `int` | No | Max age in seconds (default 300) |
 
+\* Technically optional, but the backend always sends it. Omitting it skips timestamp-based signing and freshness checks.
+
 ---
 
 ## Error Handling

commune/__init__.py

@@ -35,7 +35,7 @@
     ValidationError,
     RateLimitError,
 )
-from commune.webhooks import verify_signature, WebhookVerificationError
+from commune.webhooks import verify_signature, compute_signature, WebhookVerificationError
 
 __all__ = [
     "CommuneClient",
@@ -70,6 +70,7 @@
     "ValidationError",
     "RateLimitError",
     "verify_signature",
+    "compute_signature",
     "WebhookVerificationError",
 ]
 

commune/webhooks.py

@@ -1,4 +1,14 @@
-"""Webhook signature verification for Commune inbound webhooks."""
+"""Webhook signature verification for Commune outbound webhooks.
+
+Commune signs every webhook delivery with HMAC-SHA256. The signature is
+sent in the ``x-commune-signature`` header with a ``v1=`` prefix::
+
+    x-commune-signature: v1={hex_digest}
+    x-commune-timestamp: {unix_ms}
+
+The signed content is ``{timestamp}.{body}`` where *timestamp* is the
+value of the ``x-commune-timestamp`` header (Unix milliseconds).
+"""
 
 from __future__ import annotations
 
@@ -12,6 +22,39 @@ class WebhookVerificationError(Exception):
     """Raised when webhook signature verification fails."""
 
 
+_V1_PREFIX = "v1="
+
+
+def compute_signature(
+    payload: bytes | str,
+    secret: str,
+    timestamp: str,
+) -> str:
+    """Compute the expected ``v1=`` signature for a webhook payload.
+
+    This is useful for testing or for building your own verification
+    logic. Most callers should use :func:`verify_signature` instead.
+
+    Args:
+        payload: The raw request body.
+        secret: Your inbox webhook secret.
+        timestamp: The ``x-commune-timestamp`` header value (Unix ms).
+
+    Returns:
+        The full signature string including the ``v1=`` prefix.
+    """
+    if isinstance(payload, str):
+        payload = payload.encode("utf-8")
+
+    signed_content = f"{timestamp}.".encode("utf-8") + payload
+    digest = hmac.new(
+        secret.encode("utf-8"),
+        signed_content,
+        hashlib.sha256,
+    ).hexdigest()
+    return f"{_V1_PREFIX}{digest}"
+
+
 def verify_signature(
     payload: bytes | str,
     signature: str,
@@ -22,17 +65,20 @@ def verify_signature(
 ) -> bool:
     """Verify a Commune webhook signature.
 
-    Commune signs every webhook delivery with an HMAC-SHA256 signature
-    using your inbox webhook secret. Always verify before processing.
+    Commune signs every webhook delivery with HMAC-SHA256. The signature
+    header uses the format ``v1={hex_digest}`` and the timestamp header
+    contains Unix **milliseconds**.
 
     Args:
         payload: The raw request body (bytes or string).
-        signature: The ``X-Commune-Signature`` header value.
+        signature: The ``x-commune-signature`` header value
+            (e.g. ``"v1=5a3f2b..."``).
         secret: Your inbox webhook secret.
-        timestamp: The ``X-Commune-Timestamp`` header value (optional).
-            If provided, the signature is verified against
-            ``{timestamp}.{payload}`` and the timestamp is checked
-            for freshness.
+        timestamp: The ``x-commune-timestamp`` header value (Unix ms).
+            **Required** for proper verification — the backend always
+            includes the timestamp in the signed content. If omitted,
+            the signature is verified against the raw payload only
+            (not recommended).
         tolerance_seconds: Maximum age of the webhook in seconds
             (default 300 = 5 minutes). Only used when ``timestamp``
             is provided.
@@ -51,9 +97,9 @@ def verify_signature(
         # In your webhook handler (e.g. Flask / FastAPI):
         verify_signature(
             payload=request.body,
-            signature=request.headers["X-Commune-Signature"],
+            signature=request.headers["x-commune-signature"],
             secret="whsec_...",
-            timestamp=request.headers.get("X-Commune-Timestamp"),
+            timestamp=request.headers.get("x-commune-timestamp"),
         )
     """
     if not signature:
@@ -64,29 +110,41 @@ def verify_signature(
     if isinstance(payload, str):
         payload = payload.encode("utf-8")
 
-    # Build the signed content
+    # Build the signed content — must match backend:
+    #   computeSignature(body, timestamp, secret) → v1=HMAC(secret, "{timestamp}.{body}")
     if timestamp:
         signed_content = f"{timestamp}.".encode("utf-8") + payload
     else:
         signed_content = payload
 
-    expected = hmac.new(
+    digest = hmac.new(
         secret.encode("utf-8"),
         signed_content,
         hashlib.sha256,
     ).hexdigest()
 
-    if not hmac.compare_digest(expected, signature):
-        raise WebhookVerificationError("Invalid signature")
+    # The backend sends "v1={hex}", so we compare with the prefix.
+    # Also accept raw hex for backward compatibility.
+    expected_v1 = f"{_V1_PREFIX}{digest}"
+
+    sig_to_compare = signature
+    if not sig_to_compare.startswith(_V1_PREFIX):
+        # Caller passed raw hex — compare against raw digest
+        if not hmac.compare_digest(digest, sig_to_compare):
+            raise WebhookVerificationError("Invalid signature")
+    else:
+        if not hmac.compare_digest(expected_v1, sig_to_compare):
+            raise WebhookVerificationError("Invalid signature")
 
-    # Check timestamp freshness
+    # Check timestamp freshness — timestamp is Unix MILLISECONDS
     if timestamp and tolerance_seconds > 0:
         try:
-            ts = int(timestamp)
-            age = abs(time.time() - ts)
-            if age > tolerance_seconds:
+            ts_ms = int(timestamp)
+            age_ms = abs(time.time() * 1000 - ts_ms)
+            age_s = age_ms / 1000
+            if age_s > tolerance_seconds:
                 raise WebhookVerificationError(
-                    f"Webhook timestamp too old ({int(age)}s > {tolerance_seconds}s)"
+                    f"Webhook timestamp too old ({int(age_s)}s > {tolerance_seconds}s)"
                 )
         except ValueError:
             pass  # Non-numeric timestamp — skip freshness check

tests/test_webhook_verify.py

@@ -1,4 +1,10 @@
-"""Tests for webhook signature verification."""
+"""Tests for webhook signature verification.
+
+These tests mirror the backend's signing protocol exactly:
+  - Signature format: ``v1={HMAC-SHA256(secret, "{timestamp_ms}.{body}")}``
+  - Timestamp: Unix milliseconds (``Date.now()`` in Node.js)
+  - Headers: ``x-commune-signature``, ``x-commune-timestamp``
+"""
 
 from __future__ import annotations
 
@@ -8,41 +14,60 @@
 
 import pytest
 
-from commune.webhooks import verify_signature, WebhookVerificationError
+from commune.webhooks import verify_signature, compute_signature, WebhookVerificationError
 
 
 SECRET = "whsec_test_secret_123"
 PAYLOAD = b'{"type":"inbound","data":{"message_id":"msg_1"}}'
 
 
-def _sign(payload: bytes, secret: str, timestamp: str | None = None) -> str:
-    if timestamp:
-        signed = f"{timestamp}.".encode("utf-8") + payload
-    else:
-        signed = payload
-    return hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
-
+def _backend_sign(payload: bytes, secret: str, timestamp_ms: str) -> str:
+    """Replicate the backend's computeSignature() exactly."""
+    digest = hmac.new(
+        secret.encode("utf-8"),
+        f"{timestamp_ms}.".encode("utf-8") + payload,
+        hashlib.sha256,
+    ).hexdigest()
+    return f"v1={digest}"
 
-def test_valid_signature_no_timestamp():
-    sig = _sign(PAYLOAD, SECRET)
-    assert verify_signature(PAYLOAD, sig, SECRET) is True
 
+# ── Core verification ────────────────────────────────────────────────────────
 
-def test_valid_signature_with_timestamp():
-    ts = str(int(time.time()))
-    sig = _sign(PAYLOAD, SECRET, ts)
+def test_valid_v1_signature_with_timestamp():
+    """Standard flow: v1= prefixed signature with ms timestamp."""
+    ts = str(int(time.time() * 1000))
+    sig = _backend_sign(PAYLOAD, SECRET, ts)
     assert verify_signature(PAYLOAD, sig, SECRET, timestamp=ts) is True
 
 
 def test_valid_signature_string_payload():
-    payload_str = PAYLOAD.decode("utf-8")
-    sig = _sign(PAYLOAD, SECRET)
-    assert verify_signature(payload_str, sig, SECRET) is True
+    """Payload passed as str instead of bytes."""
+    ts = str(int(time.time() * 1000))
+    sig = _backend_sign(PAYLOAD, SECRET, ts)
+    assert verify_signature(PAYLOAD.decode("utf-8"), sig, SECRET, timestamp=ts) is True
+
+
+def test_compute_signature_matches_backend():
+    """compute_signature() produces the same output as the backend."""
+    ts = "1707667200000"
+    expected = _backend_sign(PAYLOAD, SECRET, ts)
+    assert compute_signature(PAYLOAD, SECRET, ts) == expected
+
 
+def test_raw_hex_accepted_for_backward_compat():
+    """Raw hex (no v1= prefix) still works for backward compatibility."""
+    ts = str(int(time.time() * 1000))
+    full_sig = _backend_sign(PAYLOAD, SECRET, ts)
+    raw_hex = full_sig[3:]  # strip "v1="
+    assert verify_signature(PAYLOAD, raw_hex, SECRET, timestamp=ts) is True
+
+
+# ── Error cases ──────────────────────────────────────────────────────────────
 
 def test_invalid_signature_raises():
+    ts = str(int(time.time() * 1000))
     with pytest.raises(WebhookVerificationError, match="Invalid signature"):
-        verify_signature(PAYLOAD, "bad_signature", SECRET)
+        verify_signature(PAYLOAD, "v1=bad_hex", SECRET, timestamp=ts)
 
 
 def test_missing_signature_raises():
@@ -51,19 +76,30 @@ def test_missing_signature_raises():
 
 
 def test_missing_secret_raises():
-    sig = _sign(PAYLOAD, SECRET)
+    ts = str(int(time.time() * 1000))
+    sig = _backend_sign(PAYLOAD, SECRET, ts)
     with pytest.raises(WebhookVerificationError, match="Missing webhook secret"):
-        verify_signature(PAYLOAD, sig, "")
+        verify_signature(PAYLOAD, sig, "", timestamp=ts)
+
 
+# ── Timestamp freshness ─────────────────────────────────────────────────────
 
 def test_expired_timestamp_raises():
-    old_ts = str(int(time.time()) - 600)  # 10 minutes ago
-    sig = _sign(PAYLOAD, SECRET, old_ts)
+    """Timestamp 10 minutes old (600s) should fail with 300s tolerance."""
+    old_ts = str(int(time.time() * 1000) - 600_000)
+    sig = _backend_sign(PAYLOAD, SECRET, old_ts)
     with pytest.raises(WebhookVerificationError, match="too old"):
         verify_signature(PAYLOAD, sig, SECRET, timestamp=old_ts, tolerance_seconds=300)
 
 
 def test_fresh_timestamp_passes():
-    ts = str(int(time.time()) - 10)  # 10 seconds ago
-    sig = _sign(PAYLOAD, SECRET, ts)
+    """Timestamp 10 seconds old should pass with 300s tolerance."""
+    ts = str(int(time.time() * 1000) - 10_000)
+    sig = _backend_sign(PAYLOAD, SECRET, ts)
     assert verify_signature(PAYLOAD, sig, SECRET, timestamp=ts, tolerance_seconds=300) is True
+
+
+def test_no_timestamp_verifies_raw_payload():
+    """Without timestamp, signature is computed over raw payload only."""
+    digest = hmac.new(SECRET.encode(), PAYLOAD, hashlib.sha256).hexdigest()
+    assert verify_signature(PAYLOAD, f"v1={digest}", SECRET) is True