fygaro-webhook

Webhook signature verification for Fygaro — pure Python stdlib, zero runtime deps

This helper validates the Fygaro-Signature header of incoming webhooks. It supports secret rotation (multiple active secrets), deterministic unit‑testing, and is ready for future hash algorithms.

Installation

pip install fygaro-webhook

Requires Python ≥ 3.8.

Quick start

from fygaro.webhook import FygaroWebhookValidator

validator = FygaroWebhookValidator(
    secrets=[
        "my-primary-secret",  # str or bytes
        # "my-previous-secret",   # include during rotation windows
    ]
)

if not validator.verify_signature(
    signature_header=request.headers["Fygaro-Signature"],
    body=request.body,  # raw bytes exactly as sent
):
    raise ValueError("Invalid signature")

# …process JSON, return 200…

Opt-in: detailed error handling

from fygaro.webhook import FygaroWebhookValidator, SignatureVerificationError

validator = FygaroWebhookValidator(
    secrets=["my-primary-secret"],
    raise_exceptions=True,  # Opt-in to detailed errors
)

try:
    validator.verify_signature(
        signature_header=request.headers["Fygaro-Signature"],
        body=request.body,
    )

except SignatureVerificationError as exc:
    logger.warning("Webhook rejected: %s", exc)
    return 400

API reference

class FygaroWebhookValidator

validator.verify_signature(signature_header: str, body: bytes) -> bool

Return value:

• True — signature is valid and timestamp is within max_age (unless skipped).
• False — signature mismatch, stale timestamp, or malformed header.

Exceptions exposed at package root

• SignatureVerificationError – base class
• MissingHeaderError
• TimestampInvalidError
• TimestampExpiredError
• SignatureMismatchError

Writing deterministic unit tests

To keep fixtures stable you can bypass the timestamp‑freshness check without touching production code:

validator = FygaroWebhookValidator(
    secrets=[b"test-secret"],
    unsafe_skip_ts_validation=True,  # ← test‑only flag
)

The first instance created with unsafe_skip_ts_validation=True emits a RuntimeWarning to remind you that this path is unsafe for live traffic.

License

MIT © Fygaro — support: support@fygaro.com

Changelog – @fygaro/webhook

[1.2.0] – 2025-07-10

Added

• raise_exceptions constructor flag – opt-in detailed failure reasons without breaking the legacy True/False return contract.

[1.1.0] – 2025-07-10

Added

• unsafe_skip_ts_validation constructor flag that bypasses the timestamp-freshness check. Meant only for local/unit tests; not safe for production. Emits a RuntimeWarning the first time an instance is created with the flag enabled, to minimise accidental misuse.

[1.0.0] – 2025-06-19

Added

• Initial release with FygaroWebhookValidator class.
• Supports multiple secrets & multiple v1= hashes.
• Constant-time compare and configurable timestamp window.