fix(webhooks): generate_signature returns prefixed wire form

Receivers copy-pasting `generate_signature(...)` into their handler used
to produce a bare hex digest like `"abc123..."` and had to remember to
wrap it as `f"sha256={sig}"` to match the dispatcher's wire format.
Forgetting the wrap silently produced malformed signatures that failed
verification on the other side.

`generate_signature(body, secret)` now returns the full
`"sha256=<lowercase hex>"` form, ready to be assigned to the
`X-Tango-Signature` header directly. `verify_signature` continues to
accept both the prefixed wire form and the bare-hex form so callers
that pre-strip the prefix keep working — added an explicit regression
test for that.

Audited and updated:
- `tango/webhooks/simulate.py` — `sign()` builds the header from the
  prefixed form directly; `SignedRequest.signature` field stays bare hex
- `tango/webhooks/cli.py` — uses `SIGNATURE_PREFIX` for the printed
  signature value (via the SimulationResult.signature bare-hex field)
- `tests/test_webhooks_signing.py` — vectors updated to prefixed form;
  added explicit dual-form acceptance test
- `tests/test_webhooks_receiver.py` — `_post_signed` no longer
  double-wraps the header
- `docs/WEBHOOKS.md` and `docs/API_REFERENCE.md` — receiver examples
  drop the manual `f"sha256={...}"` wrap

Breaking change for direct callers of `generate_signature` who relied
on bare-hex output — pass through `parse_signature_header()` to recover
the previous form. Folded into the v0.7.0 release.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: infinityplusone

CHANGELOG.md

@@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - `create_webhook_alert` accepts `endpoint=` (keyword-only). Required for accounts with multiple webhook endpoints; auto-resolves for single-endpoint accounts. Closes the multi-endpoint smoke-test gap (tango#2256).
 - `test_webhook_delivery` now sends the canonical `endpoint` body key instead of the deprecated `endpoint_id` alias (tango#2252). The Python kwarg name stays `endpoint_id=` for backwards compatibility; the wire payload is what changed.
+- **`generate_signature(body, secret)` now returns the full wire form `"sha256=<hex>"`** instead of bare hex. Callers can assign the return value directly to the `X-Tango-Signature` header without wrapping in a format string. This is a breaking change for code that relied on the bare-hex return; pass it through `parse_signature_header()` to recover the previous form. `verify_signature` accepts both prefixed and bare-hex inputs (unchanged), so receivers continue to work either way.
 
 ### Removed
 - **Subject-based webhook subscription surface** (tango#2275). Migrate to `create_webhook_alert(...)` and the alerts API.

docs/API_REFERENCE.md

@@ -1717,7 +1717,7 @@ The `tango.webhooks` subpackage adds testing and developer-tooling primitives on
 ```python
 from tango.webhooks import (
     verify_signature,        # (body: bytes, secret: str, header: str | None) -> bool
-    generate_signature,      # (body: bytes, secret: str) -> str (lowercase hex)
+    generate_signature,      # (body: bytes, secret: str) -> str  ("sha256=<hex>" wire form)
     parse_signature_header,  # (header: str | None) -> str | None  (strips "sha256=")
     SIGNATURE_HEADER,        # "X-Tango-Signature"
     SIGNATURE_PREFIX,        # "sha256="

docs/WEBHOOKS.md

@@ -307,9 +307,11 @@ def test_my_handler_processes_entity_update():
     with WebhookReceiver(secret="test_secret").run() as rx:
         # Trigger whatever in your code-under-test should send a webhook
         # (e.g. a publisher, or in this case a manual POST).
-        body = b'{"events":[{"event_type":"entities.updated","uei":"ABC"}]}'
+        body = b'{"events":[{"event_type":"alerts.entity.match","alert_id":"ABC"}]}'
         sig = generate_signature(body, "test_secret")
-        httpx.post(rx.url, content=body, headers={"X-Tango-Signature": f"sha256={sig}"})
+        # generate_signature returns the wire form ("sha256=<hex>") — assign
+        # directly to the header without wrapping.
+        httpx.post(rx.url, content=body, headers={"X-Tango-Signature": sig})
 
         assert len(rx.deliveries) == 1
         assert rx.deliveries[0].verified
@@ -335,7 +337,7 @@ Each `Delivery` has: `received_at`, `path`, `signature_header`, `body_bytes`, `b
 ```python
 from tango.webhooks import sign
 
-signed = sign({"events": [{"event_type": "entities.updated"}]}, secret="s")
+signed = sign({"events": [{"event_type": "alerts.entity.match"}]}, secret="s")
 assert signed.headers["X-Tango-Signature"].startswith("sha256=")
 
 # Use `signed.body` as the raw bytes and `signed.headers` directly:

tango/webhooks/cli.py

@@ -217,13 +217,17 @@ def simulate_cmd(
         return
 
     result = simulate.deliver(target_url=target_url, payload=payload, secret=secret)
+    # `result.signature` is the bare hex on the SimulationResult dataclass;
+    # render the prefixed wire form (matches X-Tango-Signature exactly).
+    from tango.webhooks.signing import SIGNATURE_PREFIX
+
     click.echo(
         json.dumps(
             {
                 "delivered": True,
                 "target_url": target_url,
                 "status_code": result.status_code,
-                "signature": f"sha256={result.signature}",
+                "signature": f"{SIGNATURE_PREFIX}{result.signature}",
                 "sent_payload": payload,
                 "receiver_response": result.response_body[:500],
             },

tango/webhooks/signing.py

@@ -19,8 +19,15 @@
 
 
 def generate_signature(body: bytes, secret: str) -> str:
-    """Return the lowercase hex HMAC-SHA256 of ``body`` keyed by ``secret``."""
-    return hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    """Return the wire-format signature for ``body`` keyed by ``secret``.
+
+    Output is the full ``sha256=<lowercase hex>`` form Tango emits in the
+    ``X-Tango-Signature`` header, so the return value can be assigned to
+    the header directly without a wrapping format string. To get the bare
+    hex digest, strip the prefix with :func:`parse_signature_header`.
+    """
+    digest = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    return f"{SIGNATURE_PREFIX}{digest}"
 
 
 def parse_signature_header(value: str | None) -> str | None:
@@ -39,12 +46,18 @@ def parse_signature_header(value: str | None) -> str | None:
 def verify_signature(body: bytes, secret: str, signature_header: str | None) -> bool:
     """Return True if ``signature_header`` matches the HMAC of ``body``.
 
-    Uses :func:`hmac.compare_digest` for constant-time comparison.
-    Returns False for an absent or malformed header rather than raising — let
-    callers decide how to respond (typically a 401 / 403).
+    Accepts both the prefixed form (``sha256=<hex>``) and the bare-hex form
+    in ``signature_header`` — callers passing in pre-stripped headers keep
+    working. Uses :func:`hmac.compare_digest` for constant-time comparison.
+    Returns False for an absent or malformed header rather than raising —
+    let callers decide how to respond (typically a 401 / 403).
     """
     received = parse_signature_header(signature_header)
     if not received:
         return False
-    expected = generate_signature(body, secret)
+    # generate_signature now returns the prefixed wire form; strip it for
+    # the bare-hex comparison.
+    expected = parse_signature_header(generate_signature(body, secret))
+    if not expected:
+        return False
     return hmac.compare_digest(expected, received)

tango/webhooks/simulate.py

@@ -23,15 +23,15 @@
 from dataclasses import dataclass
 from typing import Any
 
-from tango.webhooks.signing import SIGNATURE_HEADER, SIGNATURE_PREFIX, generate_signature
+from tango.webhooks.signing import SIGNATURE_HEADER, generate_signature, parse_signature_header
 
 
 @dataclass(frozen=True)
 class SignedRequest:
     """A Tango-shaped signed request, ready to be POSTed."""
 
     body: bytes
-    signature: str  # bare lowercase hex
+    signature: str  # bare lowercase hex (header-prefix stripped)
     headers: dict[str, str]  # includes Content-Type and X-Tango-Signature
 
 
@@ -52,13 +52,14 @@ def sign(payload: dict[str, Any] | list[Any] | bytes | str, secret: str) -> Sign
     receive, or for hand-rolling deliveries with a custom HTTP client.
     """
     body = _to_bytes(payload)
-    signature_hex = generate_signature(body, secret)
+    header_value = generate_signature(body, secret)
+    bare_hex = parse_signature_header(header_value) or ""
     return SignedRequest(
         body=body,
-        signature=signature_hex,
+        signature=bare_hex,
         headers={
             "Content-Type": "application/json",
-            SIGNATURE_HEADER: f"{SIGNATURE_PREFIX}{signature_hex}",
+            SIGNATURE_HEADER: header_value,
         },
     )
 

tests/test_webhooks_receiver.py

@@ -15,13 +15,14 @@
 
 
 def _post_signed(url: str, body: bytes, secret: str) -> httpx.Response:
-    sig = generate_signature(body, secret)
+    # generate_signature returns the wire form ("sha256=<hex>") so it can
+    # be assigned to the header directly with no wrapping.
     return httpx.post(
         url,
         content=body,
         headers={
             "Content-Type": "application/json",
-            "X-Tango-Signature": f"sha256={sig}",
+            "X-Tango-Signature": generate_signature(body, secret),
         },
         timeout=5.0,
     )

tests/test_webhooks_signing.py

@@ -15,14 +15,15 @@
 from tango.webhooks import generate_signature, parse_signature_header, verify_signature
 
 KNOWN_VECTORS: list[tuple[bytes, str, str]] = [
-    # (body_bytes, secret, expected_lowercase_hex_hmac_sha256)
-    (b"", "dev_secret", hmac.new(b"dev_secret", b"", hashlib.sha256).hexdigest()),
+    # (body_bytes, secret, expected_wire_signature) — full sha256=<hex> form
+    (b"", "dev_secret", "sha256=" + hmac.new(b"dev_secret", b"", hashlib.sha256).hexdigest()),
     (
-        b'{"events":[{"event_type":"entities.updated","uei":"ABC123"}]}',
+        b'{"events":[{"event_type":"alerts.entity.match","alert_id":"ABC"}]}',
         "shh",
-        hmac.new(
+        "sha256="
+        + hmac.new(
             b"shh",
-            b'{"events":[{"event_type":"entities.updated","uei":"ABC123"}]}',
+            b'{"events":[{"event_type":"alerts.entity.match","alert_id":"ABC"}]}',
             hashlib.sha256,
         ).hexdigest(),
     ),
@@ -34,29 +35,50 @@ def test_generate_signature_matches_reference_algorithm() -> None:
         assert generate_signature(body, secret) == expected
 
 
-def test_generate_signature_is_lowercase_hex() -> None:
+def test_generate_signature_returns_prefixed_wire_form() -> None:
+    """generate_signature returns the full ``sha256=<hex>`` header value, so
+    callers can assign it directly to X-Tango-Signature without wrapping."""
     sig = generate_signature(b"payload", "secret")
-    assert sig == sig.lower()
-    int(sig, 16)  # must parse as hex
+    assert sig.startswith("sha256=")
+    bare = sig[len("sha256=") :]
+    assert bare == bare.lower()
+    int(bare, 16)  # must parse as hex
 
 
 def test_verify_signature_round_trip() -> None:
-    body = b'{"events":[{"event_type":"awards.created"}]}'
+    body = b'{"events":[{"event_type":"alerts.contract.match"}]}'
     secret = "rotating-secret"
     sig = generate_signature(body, secret)
-    assert verify_signature(body, secret, f"sha256={sig}") is True
-    assert verify_signature(body, secret, sig) is True  # bare hex also accepted
+    # Prefixed form (what generate_signature returns and what Tango sends)
+    assert verify_signature(body, secret, sig) is True
+    # Bare-hex form (callers passing pre-stripped headers)
+    bare = parse_signature_header(sig)
+    assert bare is not None
+    assert verify_signature(body, secret, bare) is True
+
+
+def test_verify_signature_accepts_both_prefixed_and_bare_hex() -> None:
+    """Regression test: verify_signature must accept BOTH the wire form
+    (sha256=<hex>) and the pre-stripped bare-hex form. Callers that strip
+    the prefix themselves before passing in must keep working."""
+    body = b"hello"
+    secret = "k"
+    sig = generate_signature(body, secret)
+    bare = parse_signature_header(sig)
+    assert bare is not None and bare != sig  # sanity: they really differ
+    assert verify_signature(body, secret, sig) is True
+    assert verify_signature(body, secret, bare) is True
 
 
 def test_verify_signature_rejects_tampered_body() -> None:
     secret = "secret"
     sig = generate_signature(b"original", secret)
-    assert verify_signature(b"tampered", secret, f"sha256={sig}") is False
+    assert verify_signature(b"tampered", secret, sig) is False
 
 
 def test_verify_signature_rejects_wrong_secret() -> None:
     sig = generate_signature(b"body", "right")
-    assert verify_signature(b"body", "wrong", f"sha256={sig}") is False
+    assert verify_signature(b"body", "wrong", sig) is False
 
 
 def test_verify_signature_handles_missing_or_empty_header() -> None: