Webhooks

curl -X POST https://qa.tidy.engineering/api/v1/event_subscriptions \
  -H "Authorization: Bearer $TIDY_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example/tidy-webhook",
    "event_types": ["email.created", "task.updated"]
  }'

"""
Tidy webhook signature verification (Python reference implementation).

Mirrors services/event-dispatcher/src/event_dispatcher/signing.py so that a
partner who copy-pastes this file can verify real Tidy deliveries.

Header format:
    Tidy-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>

HMAC input:  f"{t}.".encode() + raw_body_bytes
Secret:      the webhook subscription's current signing secret.
             During 7-day rotation we accept both current and previous.
"""

from __future__ import annotations

import hashlib
import hmac
import time


def verify_tidy_signature(
    header_value: str,
    raw_body: bytes,
    secrets: list[str],
    *,
    now: int | None = None,
    tolerance_seconds: int = 300,
) -> bool:
    """Return True if the signature is valid.

    Parameters
    ----------
    header_value:
        The raw value of the `Tidy-Signature` HTTP header.
    raw_body:
        The exact bytes of the HTTP request body. Do NOT re-serialize JSON —
        the HMAC is over the bytes we sent, byte-for-byte.
    secrets:
        A list of signing secrets accepted for this subscription. During a
        rotation window this contains both the current and previous secret.
    now:
        Current unix time in seconds (override for tests).
    tolerance_seconds:
        Replay window. Defaults to 5 minutes.
    """
    if now is None:
        now = int(time.time())

    try:
        parts = dict(p.split("=", 1) for p in header_value.split(","))
        t = int(parts["t"])
        v1 = parts["v1"]
    except (ValueError, KeyError):
        return False

    if abs(now - t) > tolerance_seconds:
        return False

    mac_input = f"{t}.".encode("utf-8") + raw_body
    for secret in secrets:
        expected = hmac.new(
            secret.encode("utf-8"), mac_input, hashlib.sha256
        ).hexdigest()
        if hmac.compare_digest(expected, v1):
            return True

    return False


# Flask example:
#
#     from flask import request, abort
#
#     @app.post("/tidy-webhook")
#     def receive():
#         sig = request.headers.get("Tidy-Signature", "")
#         if not verify_tidy_signature(sig, request.get_data(), [SIGNING_SECRET]):
#             abort(401)
#         event = request.get_json()
#         handle(event)
#         return "", 204