feat: add webhook signature verification helper

The SDK accepts webhook_url on experiment creation but has nothing for
verifying the deliveries that arrive, so every integrator hand-writes the
HMAC check from the docs snippet. That snippet is correct; the code built
around it is where the quiet failures live.

Adds adaptyv.webhooks.verify, which takes the raw body bytes, the request
headers, and the webhook secret, and returns a frozen WebhookEvent or
raises. Stdlib only, no framework imports, no new runtime dependencies.

Two new leaves on AdaptyvError, deliberately siblings so that catching one
cannot swallow the other. WebhookVerificationError means the delivery never
proved it came from Foundry and should be answered 4xx. WebhookPayloadError
is raised only after the signature checks out, so the delivery is genuine
and only its shape is at issue; answering that 4xx would discard a real
event, since 4xx is permanent in the retry model.

Event name and delivery id are read from the signed body rather than the
X-Adaptyv-Event and X-Adaptyv-Delivery-Id headers, which the signature does
not cover.

Author: EsraaKamel11

README.md

@@ -58,6 +58,7 @@ print(f"Experiment: {result.experiment_url}")
 
 - Picks up `ADAPTYV_API_KEY` and `ADAPTYV_API_URL` from environment
 - Retries on failure with exponential backoff
+- Signature verification for incoming webhooks
 - Type hints throughout
 - Context managers for cleanup
 - Requires Python 3.11+
@@ -156,6 +157,87 @@ for result in results.items:
     print(f"{result.title}: {result.result_type}")
 ```
 
+### Verify webhooks
+
+Pass a `webhook_url` when you create an experiment and Foundry POSTs status updates
+to it instead of making you poll. Every delivery is signed, so check the signature
+before trusting the payload:
+
+```python
+from adaptyv.exceptions import WebhookPayloadError, WebhookVerificationError
+from adaptyv.webhooks import verify
+
+try:
+    # raw_body must be the bytes that arrived, not a parsed or re-serialized payload
+    event = verify(raw_body, request_headers, WEBHOOK_SECRET)
+except WebhookVerificationError:
+    ...  # not from Foundry, or damaged in transit: reject it
+except WebhookPayloadError:
+    ...  # signed by Foundry, but the envelope did not parse: log it, let it retry
+
+print(event.event)        # "experiment_update"
+print(event.delivery_id)  # "019b8da3-4a91-16c6-fa94-619212bee6a6"
+print(event.payload["data"]["experiment_code"])
+```
+
+`verify` never returns a boolean. It raises, and which exception it raises is what
+you branch on:
+
+| Exception | Meaning | Answer with |
+| --- | --- | --- |
+| `WebhookVerificationError` | A missing or malformed `X-Adaptyv-Signature`, a signature that does not match the body, an empty secret, or a body that is not raw bytes. The delivery never proved it came from Foundry. | 4xx |
+| `WebhookPayloadError` | The signature checked out, but the envelope was not readable JSON carrying an `event` and a `delivery_id`. | 5xx, or accept and log |
+
+The split matters because 4xx is permanent in the retry model. Answering 4xx to a
+genuinely signed delivery whose shape you did not expect throws away a real event and
+tells Foundry never to send it again. The two are siblings rather than parent and
+child, so catching one cannot swallow the other by accident.
+
+`event.payload` is the whole envelope exactly as it arrived, so fields the SDK does
+not know about pass through untouched.
+
+With FastAPI:
+
+```python
+import logging
+import os
+
+from fastapi import FastAPI, Request, Response
+
+from adaptyv.exceptions import WebhookPayloadError, WebhookVerificationError
+from adaptyv.webhooks import verify
+
+app = FastAPI()
+WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]
+
+
+@app.post("/foundry-hook")
+async def foundry_hook(request: Request) -> Response:
+    try:
+        event = verify(await request.body(), request.headers, WEBHOOK_SECRET)
+    except WebhookVerificationError:
+        return Response(status_code=400)  # permanent, and correctly so
+    except WebhookPayloadError:
+        logging.exception("unreadable webhook envelope")
+        return Response(status_code=500)  # genuinely ours, so let it come back
+
+    handle(event)  # your code, keyed on event.delivery_id
+    return Response(status_code=200)
+```
+
+`await request.body()` hands back the raw bytes. Reading `await request.json()` and
+re-serializing it produces different bytes than the ones that were signed, so the
+signature would never match. The equivalent accessor is `request.get_data()` on
+Flask and `request.body` on Django.
+
+**Handlers have to be idempotent.** A delivery is retried up to three times with
+exponential backoff on network errors and 5xx responses, so a handler that fails
+once is guaranteed to see the same event again. `event.delivery_id` is stable across
+those attempts, which makes it the key to deduplicate on in whatever store you
+already have. The SDK deliberately does not keep one for you. Return 2xx to
+acknowledge a delivery; a 4xx tells Foundry the failure is permanent and stops the
+retries.
+
 ---
 
 ## Examples
@@ -225,4 +307,3 @@ The SDK is pegged to the deployed OpenAPI spec
   so an API change surfaces as a failed build instead of silent drift. When it
   fires: run `mise run gen:types`, bump `FOUNDRY_SPEC_VERSION`, add any new
   client method, and commit.
-

src/adaptyv/__init__.py

@@ -12,6 +12,8 @@
     PermissionDeniedError,
     RateLimitError,
     ValidationError,
+    WebhookPayloadError,
+    WebhookVerificationError,
 )
 
 __all__ = [
@@ -47,6 +49,8 @@
     "PermissionDeniedError",
     "RateLimitError",
     "ValidationError",
+    "WebhookPayloadError",
+    "WebhookVerificationError",
 ]
 
 # Lazy import mapping: name -> (module_path, attribute_name)

src/adaptyv/exceptions.py

@@ -7,7 +7,9 @@
     │   ├── NotFoundError (404, resource not found)
     │   └── RateLimitError (429, rate limit exceeded with retry_after)
     ├── ValidationError (invalid input parameters)
-    └── PermissionDeniedError (API key lacks create_experiment permission)
+    ├── PermissionDeniedError (API key lacks create_experiment permission)
+    ├── WebhookVerificationError (webhook delivery could not be trusted)
+    └── WebhookPayloadError (webhook delivery was trusted but unreadable)
 """
 
 from __future__ import annotations
@@ -144,3 +146,28 @@ def __init__(
             request_id=request_id,
             request_path=request_path,
         )
+
+
+class WebhookVerificationError(AdaptyvError):
+    """Webhook delivery could not be trusted.
+
+    Raised by adaptyv.webhooks.verify when a delivery fails to prove it came
+    from Foundry: a bad, missing, or malformed signature, an empty secret, or a
+    body that is not raw bytes. Handlers should answer 4xx, which the API
+    treats as permanent and does not retry, because nothing about resending an
+    unverifiable request would make it verify.
+    """
+
+
+class WebhookPayloadError(AdaptyvError):
+    """Webhook delivery was authentic but its envelope could not be read.
+
+    Raised by adaptyv.webhooks.verify only after the signature has checked out,
+    so the delivery provably came from Foundry and only its shape is at issue.
+    Handlers should answer 5xx or accept and log, never 4xx: a permanent
+    rejection discards a real event and tells the API never to send it again.
+
+    Deliberately a sibling of WebhookVerificationError rather than a subclass,
+    so that a handler catching the verification error to answer 4xx cannot
+    swallow this one by accident.
+    """

src/adaptyv/webhooks.py

@@ -0,0 +1,184 @@
+"""Webhook signature verification for Foundry deliveries.
+
+Foundry POSTs signed events to the webhook_url registered on an experiment.
+Each delivery carries X-Adaptyv-Signature, which is "sha256=<hex>" over the
+HMAC-SHA256 of the raw request body, alongside X-Adaptyv-Event and
+X-Adaptyv-Delivery-Id. The contract is documented at
+https://docs.adaptyvbio.com/api-reference/api-introduction.
+
+verify() is framework-agnostic on purpose: hand it the raw body bytes, the
+request headers, and the webhook secret, and it either returns a WebhookEvent
+or raises WebhookVerificationError. The README has FastAPI and framework-free
+handlers built on it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from adaptyv.exceptions import WebhookPayloadError, WebhookVerificationError
+
+SIGNATURE_HEADER = "X-Adaptyv-Signature"
+
+_SIGNATURE_PREFIX = "sha256="
+_DIGEST_SIZE = hashlib.sha256().digest_size
+
+
+@dataclass(frozen=True)
+class WebhookEvent:
+    """A webhook delivery whose signature has been verified.
+
+    Attributes:
+        event: Event slug, for example "experiment_update".
+        delivery_id: Unique id for this delivery attempt. Foundry retries a
+            failed delivery up to three times, so a handler that errors once
+            will see this id again and should use it as its dedupe key.
+        payload: The whole parsed envelope, including timestamp, api_version,
+            and the nested data object.
+    """
+
+    event: str
+    delivery_id: str
+    payload: dict[str, Any]
+
+
+def _get_header(headers: Mapping[str, str], name: str) -> str | None:
+    """Look up a header without depending on the caller's capitalization.
+
+    Frameworks disagree here: httpx and Starlette hand back case-insensitive
+    mappings, while dict(request.headers) hands back whatever casing arrived on
+    the wire. HTTP header names are case-insensitive, so this treats them so.
+    """
+    value = headers.get(name)
+    if value is not None:
+        return value
+
+    wanted = name.lower()
+    for key, candidate in headers.items():
+        if key.lower() == wanted:
+            return candidate
+    return None
+
+
+def _parse_signature(headers: Mapping[str, str]) -> bytes:
+    """Decode the digest carried by the signature header.
+
+    Returns the digest decoded to bytes rather than the hex text it arrived as,
+    so the comparison cannot turn on the casing the sender chose.
+
+    Raises:
+        WebhookVerificationError: The header is absent or cannot be parsed.
+    """
+    header = _get_header(headers, SIGNATURE_HEADER)
+    if header is None:
+        raise WebhookVerificationError(f"{SIGNATURE_HEADER} header is missing from the delivery")
+
+    if not header.startswith(_SIGNATURE_PREFIX):
+        raise WebhookVerificationError(
+            f"{SIGNATURE_HEADER} must be formatted as 'sha256=<hex>', got {header!r}"
+        )
+
+    hex_digest = header[len(_SIGNATURE_PREFIX) :]
+    try:
+        digest = bytes.fromhex(hex_digest)
+    except ValueError as exc:
+        raise WebhookVerificationError(
+            f"{SIGNATURE_HEADER} digest is not valid hex: {hex_digest!r}"
+        ) from exc
+
+    if len(digest) != _DIGEST_SIZE:
+        raise WebhookVerificationError(
+            f"{SIGNATURE_HEADER} digest must be {_DIGEST_SIZE} bytes, got {len(digest)}"
+        )
+    return digest
+
+
+def _parse_payload(body: bytes) -> dict[str, Any]:
+    """Parse an already verified body into an event envelope.
+
+    Raises:
+        WebhookPayloadError: The body is not a JSON object. Not a verification
+            failure: the signature already proved where these bytes came from.
+    """
+    try:
+        payload = json.loads(body)
+    except ValueError as exc:
+        raise WebhookPayloadError(f"Webhook body is not valid JSON: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise WebhookPayloadError(
+            f"Webhook body must be a JSON object, got {type(payload).__name__}"
+        )
+    return payload
+
+
+def _required_str(payload: dict[str, Any], key: str) -> str:
+    """Read an envelope field that WebhookEvent types as str.
+
+    Raises:
+        WebhookPayloadError: The field is absent or is not a string.
+    """
+    value = payload.get(key)
+    if not isinstance(value, str):
+        raise WebhookPayloadError(f"Webhook payload has no string {key!r} field")
+    return value
+
+
+def verify(body: bytes, headers: Mapping[str, str], secret: str) -> WebhookEvent:
+    """Verify a webhook delivery and return the event it carries.
+
+    Args:
+        body: The raw request body, exactly as it arrived. A str or an already
+            parsed payload is refused, because re-serializing a payload changes
+            the bytes the signature was computed over.
+        headers: The request headers, looked up case-insensitively.
+        secret: The webhook secret for this endpoint.
+
+    Returns:
+        The verified event. Its event name and delivery id come from the signed
+        body, not from the X-Adaptyv-Event and X-Adaptyv-Delivery-Id headers,
+        which the signature does not cover. The whole envelope is exposed
+        unchanged on payload, so fields this SDK does not know about pass
+        through rather than being dropped.
+
+    Raises:
+        WebhookVerificationError: The delivery did not prove it came from
+            Foundry. The body is not bytes, the secret is empty, the signature
+            header is missing or malformed, or the signature does not match.
+            Answer 4xx: resending would not help.
+        WebhookPayloadError: The signature checked out but the envelope could
+            not be read. Answer 5xx or accept and log, never 4xx, or a genuine
+            event is discarded and the API is told not to retry it.
+    """
+    if not isinstance(body, bytes):
+        raise WebhookVerificationError(
+            "Webhook body must be the raw request body as bytes, got "
+            f"{type(body).__name__}. Re-serializing a parsed payload produces "
+            "different bytes than the ones that were signed."
+        )
+
+    if not isinstance(secret, str) or not secret.strip():
+        raise WebhookVerificationError(
+            "Webhook secret must be a non-empty string. An unset secret still "
+            "produces a valid HMAC, so verification would pass for every request "
+            "instead of failing closed."
+        )
+
+    provided = _parse_signature(headers)
+    expected = hmac.new(secret.encode(), body, hashlib.sha256).digest()
+    if not hmac.compare_digest(expected, provided):
+        raise WebhookVerificationError("Webhook signature does not match the request body")
+
+    # Parsed only after the signature checks out, so an unverified body never
+    # reaches the JSON parser.
+    payload = _parse_payload(body)
+    return WebhookEvent(
+        event=_required_str(payload, "event"),
+        delivery_id=_required_str(payload, "delivery_id"),
+        payload=payload,
+    )