agentrust-py 0.0.3__py3-none-any.whl

agentrust_sdk/webhooks.py

@@ -0,0 +1,782 @@
+"""
+AgentTrust SDK — Webhook dispatcher.
+
+Inspired by the Adrian OSS webhook notification system, this module provides
+a tier-gated, configurable webhook dispatcher that fires HTTP notifications
+to registered endpoints whenever a validation result matches the configured
+decision filter.
+
+Supported platforms
+-------------------
+- discord : Rich colour-coded embeds with decision outcome, risk tier, and
+            agent details. Adrian-style formatting with severity colours.
+- http    : Plain JSON payload; compatible with Slack incoming webhooks,
+            PagerDuty, Linear, and any generic HTTP receiver.
+
+Tier requirement
+----------------
+Capability.WEBHOOKS requires **Team** tier or above. On lower tiers the
+dispatcher is constructed but ``dispatch()`` / ``async_dispatch()`` are
+no-ops that emit a single ``logger.debug`` message.
+
+Usage (Team tier and above)
+---------------------------
+Programmatic::
+
+    from agentrust_sdk.webhooks import WebhookDispatcher
+
+    dispatcher = WebhookDispatcher(tier=client.tier)
+    dispatcher.register(
+        url="https://discord.com/api/webhooks/1234/token",
+        events=["block", "escalate"],
+        name="alerts-channel",
+    )
+
+    # AgentTrustClient calls this automatically when a dispatcher is attached.
+    # You can also call it manually after validate():
+    from agentrust_sdk.webhooks import event_from_response
+    result = client.validate(agent_id="my-agent", user="alice", input="Pay $500")
+    dispatcher.dispatch(event_from_response(result, agent_id="my-agent"))
+
+Via environment variables (zero code required)::
+
+    AGENTRUST_WEBHOOK_URL=https://discord.com/api/webhooks/...
+    AGENTRUST_WEBHOOK_EVENTS=block,escalate    # or "all"
+
+Environment variables
+---------------------
+AGENTRUST_WEBHOOK_URL      Single webhook URL — bootstrapped on dispatcher init.
+AGENTRUST_WEBHOOK_EVENTS   Comma-separated decision filter: all|approve|block|escalate
+                             Defaults to "all" when AGENTRUST_WEBHOOK_URL is set.
+AGENTRUST_WEBHOOK_DB       SQLite path for the webhook registry.
+                             Default: ~/.agentrust/webhooks.db
+AGENTRUST_WEBHOOK_TIMEOUT  HTTP timeout in seconds for each dispatch call (default 5).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sqlite3
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+from pydantic import BaseModel, Field
+
+from .config import SDK_CONFIG
+from .tiers import Capability, Tier, is_allowed, UPGRADE_MESSAGES
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_DISCORD_HOSTS = (
+    "https://discord.com/api/webhooks/",
+    "https://discordapp.com/api/webhooks/",
+)
+
+# Colour palette mirrors Adrian: M4-red / M3-amber / neutral
+_DECISION_COLORS: dict[str, int] = {
+    "block":            0xFF4757,   # danger red
+    "escalate":         0xFFA502,   # warning amber
+    "request_evidence": 0xFFA502,   # warning amber
+    "approve":          0x2ED573,   # success green
+    "pending":          0x6B6B80,   # muted neutral
+}
+
+_VISIBLE_TOKEN_SUFFIX = 8   # chars of a webhook token shown in masked form
+
+_VALID_EVENTS = frozenset({"all", "approve", "block", "escalate", "request_evidence"})
+
+
+# ---------------------------------------------------------------------------
+# Pydantic models
+# ---------------------------------------------------------------------------
+
+def _utcnow_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z")
+
+
+class WebhookConfig(BaseModel):
+    """Full (internal) representation of a registered webhook."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    url: str
+    events: list[str] = Field(default_factory=lambda: ["all"])
+    platform: str = "http"   # "discord" | "http"
+    name: str = ""
+    enabled: bool = True
+    created_at: str = Field(default_factory=_utcnow_iso)
+
+
+class WebhookConfigPublic(BaseModel):
+    """Safe-to-expose representation: the URL's secret token is masked."""
+
+    id: str
+    url_masked: str
+    events: list[str]
+    platform: str
+    name: str
+    enabled: bool
+    created_at: str
+
+
+class WebhookEvent(BaseModel):
+    """The normalised event payload fired to every matching webhook endpoint."""
+
+    envelope_id: str
+    agent_id: str
+    decision: str           # "approve" | "block" | "escalate" | "request_evidence" | "pending"
+    risk_tier: str = "unknown"
+    risk_score: float = 0.0
+    session_id: str | None = None
+    framework: str = "REST"
+    timestamp: str = Field(default_factory=_utcnow_iso)
+    sdk_version: str = Field(default_factory=lambda: SDK_CONFIG.sdk_version)
+
+
+# ---------------------------------------------------------------------------
+# URL helpers
+# ---------------------------------------------------------------------------
+
+def is_discord_url(url: str) -> bool:
+    """Return True if *url* points at a Discord webhook endpoint."""
+    return any(url.startswith(h) for h in _DISCORD_HOSTS)
+
+
+def validate_webhook_url(url: str) -> None:
+    """
+    Raise ``ValueError`` if *url* is not a valid HTTPS webhook endpoint.
+
+    Mirrors Adrian's ``ValidateDiscordWebhookURL`` but is broader:
+    any well-formed HTTPS URL is accepted; Discord URLs get an extra host
+    prefix check via ``is_discord_url`` at registration time (informational
+    only — non-Discord URLs are allowed as generic HTTP targets).
+    """
+    if not url.startswith("https://"):
+        raise ValueError(
+            f"Webhook URL must use HTTPS. "
+            f"Got: {url!r}. "
+            f"Discord example: https://discord.com/api/webhooks/..."
+        )
+    parsed = urlparse(url)
+    if not parsed.netloc:
+        raise ValueError(f"Invalid webhook URL (no host): {url!r}")
+    if not parsed.path or parsed.path == "/":
+        raise ValueError(f"Webhook URL must include a path: {url!r}")
+
+
+def mask_url(url: str) -> str:
+    """
+    Return the URL with its secret token replaced by a fixed prefix + last
+    ``_VISIBLE_TOKEN_SUFFIX`` characters.
+
+    Discord shape:  https://discord.com/api/webhooks/<id>/<token>
+    Generic shape:  anything after the last '/' is treated as the secret.
+
+    Mirrors Adrian's ``store.MaskedURL`` logic exactly.
+    """
+    last_slash = url.rfind("/")
+    if last_slash == -1 or last_slash == len(url) - 1:
+        return url
+    token = url[last_slash + 1:]
+    if len(token) > _VISIBLE_TOKEN_SUFFIX:
+        visible = token[-_VISIBLE_TOKEN_SUFFIX:]
+        return url[: last_slash + 1] + "...***" + visible
+    return url
+
+
+# ---------------------------------------------------------------------------
+# Event-filter matcher
+# ---------------------------------------------------------------------------
+
+def _matches_filter(event_filter: list[str], decision: str) -> bool:
+    """
+    Return True when *decision* should trigger the webhook.
+
+    ``"all"`` in the filter matches every decision outcome (mirrors Adrian's
+    ``alertTypeMatches`` with filter == "all").  Other filter entries are
+    exact-matched against the decision string.
+    """
+    if "all" in event_filter:
+        return True
+    return decision in event_filter
+
+
+# ---------------------------------------------------------------------------
+# SQLite persistence (consistent with agentrust_sdk's queue.db pattern)
+# ---------------------------------------------------------------------------
+
+def _db_path() -> Path:
+    return Path(
+        os.environ.get(
+            "AGENTRUST_WEBHOOK_DB",
+            str(Path.home() / ".agentrust" / "webhooks.db"),
+        )
+    )
+
+
+def _open_db(path: Path) -> sqlite3.Connection:
+    """Open (creating if needed) the webhook registry SQLite database."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    con = sqlite3.connect(str(path))
+    con.execute("PRAGMA journal_mode=WAL")
+    con.execute("PRAGMA synchronous=NORMAL")
+    con.execute("PRAGMA foreign_keys=ON")
+    con.execute(
+        """
+        CREATE TABLE IF NOT EXISTS webhooks (
+            id          TEXT    PRIMARY KEY,
+            url         TEXT    NOT NULL,
+            events      TEXT    NOT NULL DEFAULT '["all"]',
+            platform    TEXT    NOT NULL DEFAULT 'http',
+            name        TEXT    NOT NULL DEFAULT '',
+            enabled     INTEGER NOT NULL DEFAULT 1
+                            CHECK (enabled IN (0,1)),
+            created_at  TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+        )
+        """
+    )
+    con.commit()
+    return con
+
+
+# ---------------------------------------------------------------------------
+# Payload builders
+# ---------------------------------------------------------------------------
+
+def _build_discord_payload(event: WebhookEvent) -> dict[str, Any]:
+    """
+    Build a Discord webhook POST body with a colour-coded rich embed.
+
+    Colour coding mirrors Adrian's ``buildPayload``:
+      block / escalate  → danger red / warning amber
+      approve           → success green
+      other             → neutral grey
+    """
+    color = _DECISION_COLORS.get(event.decision, _DECISION_COLORS["pending"])
+
+    title_map = {
+        "block":            "AgentTrust: Agent Blocked",
+        "escalate":         "AgentTrust: Human Review Required",
+        "request_evidence": "AgentTrust: Evidence Requested",
+        "approve":          "AgentTrust: Action Approved",
+        "pending":          "AgentTrust: Validation Pending",
+    }
+    title = title_map.get(event.decision, "AgentTrust: Validation Result")
+
+    desc_map = {
+        "block": (
+            "An agent action was **blocked** by AgentTrust. "
+            "Review the decision details and inspect the agent output."
+        ),
+        "escalate": (
+            "An agent action requires **human review** before proceeding. "
+            "Approve or reject it via your AgentTrust dashboard."
+        ),
+        "request_evidence": (
+            "AgentTrust is requesting additional **evidence** "
+            "before approving this action."
+        ),
+        "approve": "An agent action was **approved** by AgentTrust.",
+        "pending": "AgentTrust validation completed with a **pending** status.",
+    }
+    desc = desc_map.get(event.decision, "AgentTrust validation completed.")
+
+    fields: list[dict[str, Any]] = [
+        {"name": "Decision",   "value": event.decision.upper(), "inline": True},
+        {"name": "Risk tier",  "value": event.risk_tier,        "inline": True},
+        {"name": "Risk score", "value": f"{event.risk_score:.2f}", "inline": True},
+        {"name": "Agent",      "value": event.agent_id,         "inline": True},
+        {"name": "Framework",  "value": event.framework,        "inline": True},
+    ]
+    if event.session_id:
+        fields.append({"name": "Session", "value": event.session_id, "inline": False})
+
+    return {
+        "content": (
+            f"AgentTrust alert: **{event.decision.upper()}** "
+            f"— agent `{event.agent_id}`"
+        ),
+        "embeds": [
+            {
+                "title":       title,
+                "description": desc,
+                "color":       color,
+                "fields":      fields,
+                "timestamp":   event.timestamp,
+                "footer": {
+                    "text": (
+                        f"envelope: {event.envelope_id} "
+                        f"· sdk v{event.sdk_version}"
+                    )
+                },
+            }
+        ],
+    }
+
+
+def _build_http_payload(event: WebhookEvent) -> dict[str, Any]:
+    """
+    Build a generic JSON payload for non-Discord HTTP webhook receivers.
+
+    Compatible with Slack incoming webhooks, PagerDuty events API, Linear,
+    and any endpoint that accepts JSON.
+    """
+    return {
+        "source":      "agentrust-sdk",
+        "sdk_version": event.sdk_version,
+        "event": {
+            "envelope_id": event.envelope_id,
+            "agent_id":    event.agent_id,
+            "decision":    event.decision,
+            "risk_tier":   event.risk_tier,
+            "risk_score":  event.risk_score,
+            "session_id":  event.session_id,
+            "framework":   event.framework,
+            "timestamp":   event.timestamp,
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# WebhookDispatcher
+# ---------------------------------------------------------------------------
+
+class WebhookDispatcher:
+    """
+    Manages webhook registrations and dispatches ``WebhookEvent`` objects to
+    all matching, enabled endpoints after each validation call.
+
+    The dispatcher is tier-gated: ``Capability.WEBHOOKS`` requires **Team**
+    tier or above.  On lower tiers the constructor succeeds (so code paths
+    stay clean) but all dispatch calls silently no-op.
+
+    Persistence
+    -----------
+    Webhook registrations are stored in a local SQLite database at
+    ``~/.agentrust/webhooks.db`` (overridden by ``AGENTRUST_WEBHOOK_DB``).
+    This mirrors the existing ``queue.db`` pattern in the SDK's client module.
+
+    Quick-start via env vars
+    ------------------------
+    Set these before your process starts::
+
+        AGENTRUST_WEBHOOK_URL=https://discord.com/api/webhooks/...
+        AGENTRUST_WEBHOOK_EVENTS=block,escalate
+
+    The dispatcher bootstraps a webhook from these env vars on ``__init__``
+    so you don't need any code changes beyond attaching the dispatcher to the
+    client.
+
+    Thread safety
+    -------------
+    SQLite connections are opened and closed per-call (no shared connection
+    state), so the dispatcher is safe to use from multiple threads without
+    additional locking.
+    """
+
+    def __init__(
+        self,
+        tier: Tier = Tier.OSS,
+        timeout: float | None = None,
+        *,
+        _db_override: Path | None = None,
+    ) -> None:
+        self._tier = tier
+        self._allowed = is_allowed(Capability.WEBHOOKS, tier)
+        self._timeout = (
+            timeout
+            if timeout is not None
+            else float(os.environ.get("AGENTRUST_WEBHOOK_TIMEOUT", "5"))
+        )
+        self._db = _db_override or _db_path()
+
+        if not self._allowed:
+            logger.debug(
+                "[AgentTrust] WebhookDispatcher: tier=%s does not support webhooks "
+                "(requires Team). Dispatch calls will be no-ops.",
+                tier.value,
+            )
+            return
+
+        # Bootstrap env-var webhook at startup (idempotent — checks for duplicates).
+        env_url = os.environ.get("AGENTRUST_WEBHOOK_URL", "").strip()
+        if env_url:
+            env_events_raw = os.environ.get("AGENTRUST_WEBHOOK_EVENTS", "all").strip()
+            env_events = [e.strip() for e in env_events_raw.split(",") if e.strip()]
+            try:
+                existing = self._load_from_db()
+                if not any(w.url == env_url for w in existing):
+                    self.register(
+                        url=env_url,
+                        events=env_events,
+                        name="env-config",
+                    )
+                    logger.info(
+                        "[AgentTrust] Webhook bootstrapped from AGENTRUST_WEBHOOK_URL"
+                        " (events=%s)", env_events,
+                    )
+            except Exception as exc:
+                logger.warning(
+                    "[AgentTrust] Failed to register env-var webhook: %s", exc
+                )
+
+    # ── Registration ─────────────────────────────────────────────────────────
+
+    def register(
+        self,
+        url: str,
+        events: list[str] | None = None,
+        name: str = "",
+        platform: str | None = None,
+        enabled: bool = True,
+    ) -> WebhookConfigPublic:
+        """
+        Register a new webhook destination.
+
+        Parameters
+        ----------
+        url:
+            The HTTPS webhook endpoint. Discord URLs are auto-detected; any
+            valid HTTPS URL is accepted as a generic HTTP target.
+        events:
+            List of decision outcomes that trigger dispatch.
+            Valid values: ``"all"``, ``"approve"``, ``"block"``,
+            ``"escalate"``, ``"request_evidence"``.
+            Defaults to ``["all"]``.
+        name:
+            Human-readable label shown in ``list_webhooks()`` (optional).
+        platform:
+            ``"discord"`` or ``"http"``. Auto-detected from the URL if
+            not provided.
+        enabled:
+            Set to ``False`` to register a webhook without activating it.
+
+        Returns
+        -------
+        ``WebhookConfigPublic`` with the URL's secret token masked.
+
+        Raises
+        ------
+        ``TierGateWebhookError``
+            When the dispatcher's tier is below Team.
+        ``ValueError``
+            When the URL fails basic HTTPS validation.
+        """
+        if not self._allowed:
+            raise TierGateWebhookError(
+                UPGRADE_MESSAGES.get(
+                    Capability.WEBHOOKS,
+                    "Webhooks require Team tier ($149/mo). "
+                    "Upgrade: agentrust upgrade",
+                )
+            )
+
+        validate_webhook_url(url)
+
+        _events = events if events is not None else ["all"]
+        _platform = platform or ("discord" if is_discord_url(url) else "http")
+
+        cfg = WebhookConfig(
+            url=url,
+            events=_events,
+            platform=_platform,
+            name=name,
+            enabled=enabled,
+        )
+
+        con = _open_db(self._db)
+        try:
+            con.execute(
+                "INSERT INTO webhooks "
+                "(id, url, events, platform, name, enabled, created_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (
+                    cfg.id,
+                    cfg.url,
+                    json.dumps(cfg.events),
+                    cfg.platform,
+                    cfg.name,
+                    int(cfg.enabled),
+                    cfg.created_at,
+                ),
+            )
+            con.commit()
+        finally:
+            con.close()
+
+        logger.info(
+            "[AgentTrust] Webhook registered: id=%s platform=%s events=%s name=%r",
+            cfg.id, cfg.platform, cfg.events, cfg.name,
+        )
+
+        return WebhookConfigPublic(
+            id=cfg.id,
+            url_masked=mask_url(cfg.url),
+            events=cfg.events,
+            platform=cfg.platform,
+            name=cfg.name,
+            enabled=cfg.enabled,
+            created_at=cfg.created_at,
+        )
+
+    def list_webhooks(self) -> list[WebhookConfigPublic]:
+        """
+        Return all registered webhooks with masked URLs.
+
+        Safe to call on any tier — returns an empty list when not allowed.
+        """
+        return [
+            WebhookConfigPublic(
+                id=w.id,
+                url_masked=mask_url(w.url),
+                events=w.events,
+                platform=w.platform,
+                name=w.name,
+                enabled=w.enabled,
+                created_at=w.created_at,
+            )
+            for w in self._load_from_db()
+        ]
+
+    def delete_webhook(self, webhook_id: str) -> bool:
+        """
+        Delete a registered webhook by its ID.
+
+        Returns ``True`` if the record was found and deleted, ``False``
+        if no record matched the given ID.
+        """
+        con = _open_db(self._db)
+        try:
+            cur = con.execute(
+                "DELETE FROM webhooks WHERE id = ?", (webhook_id,)
+            )
+            con.commit()
+            deleted = cur.rowcount > 0
+        finally:
+            con.close()
+
+        if deleted:
+            logger.info("[AgentTrust] Webhook deleted: id=%s", webhook_id)
+        return deleted
+
+    # ── Synchronous dispatch ──────────────────────────────────────────────────
+
+    def dispatch(self, event: WebhookEvent) -> None:
+        """
+        Synchronously fan out *event* to all matching, enabled webhooks.
+
+        Mirrors Adrian's ``fanout`` method in ``notifications/dispatcher.go``:
+          - Loads enabled webhooks from the registry.
+          - Skips webhooks whose event filter does not match the decision.
+          - POSTs to each matching webhook with a 5-second timeout.
+          - Logs a warning on individual send failures; never propagates errors
+            to the caller (fail-open: the agent's execution is not interrupted).
+
+        No-ops silently when the dispatcher's tier is below Team.
+        """
+        if not self._allowed:
+            logger.debug(
+                "[AgentTrust] Webhook dispatch skipped: tier=%s (requires Team)",
+                self._tier.value,
+            )
+            return
+
+        hooks = [w for w in self._load_from_db() if w.enabled]
+        if not hooks:
+            return
+
+        for hook in hooks:
+            if not _matches_filter(hook.events, event.decision):
+                continue
+            payload = (
+                _build_discord_payload(event)
+                if hook.platform == "discord"
+                else _build_http_payload(event)
+            )
+            try:
+                with httpx.Client(timeout=self._timeout) as http:
+                    resp = http.post(
+                        hook.url,
+                        json=payload,
+                        headers=_webhook_headers(event.sdk_version),
+                    )
+                if resp.status_code < 300:
+                    logger.debug(
+                        "[AgentTrust] Webhook dispatched: id=%s decision=%s status=%d",
+                        hook.id, event.decision, resp.status_code,
+                    )
+                else:
+                    logger.warning(
+                        "[AgentTrust] Webhook returned non-2xx: id=%s status=%d body=%r",
+                        hook.id, resp.status_code, resp.text[:256],
+                    )
+            except Exception as exc:
+                logger.warning(
+                    "[AgentTrust] Webhook dispatch error: id=%s error=%s",
+                    hook.id, exc,
+                )
+
+    # ── Asynchronous dispatch ─────────────────────────────────────────────────
+
+    async def async_dispatch(self, event: WebhookEvent) -> None:
+        """
+        Asynchronously fan out *event* to all matching, enabled webhooks.
+
+        Behaviour is identical to ``dispatch()`` but uses
+        ``httpx.AsyncClient``. Each webhook POST is awaited sequentially
+        (matching Adrian's simple loop fanout) to avoid spawning unbounded
+        tasks. Errors per-webhook are logged as warnings and never propagated.
+
+        No-ops silently when the dispatcher's tier is below Team.
+        """
+        if not self._allowed:
+            logger.debug(
+                "[AgentTrust] Async webhook dispatch skipped: tier=%s (requires Team)",
+                self._tier.value,
+            )
+            return
+
+        hooks = [w for w in self._load_from_db() if w.enabled]
+        if not hooks:
+            return
+
+        for hook in hooks:
+            if not _matches_filter(hook.events, event.decision):
+                continue
+            payload = (
+                _build_discord_payload(event)
+                if hook.platform == "discord"
+                else _build_http_payload(event)
+            )
+            try:
+                async with httpx.AsyncClient(timeout=self._timeout) as http:
+                    resp = await http.post(
+                        hook.url,
+                        json=payload,
+                        headers=_webhook_headers(event.sdk_version),
+                    )
+                if resp.status_code < 300:
+                    logger.debug(
+                        "[AgentTrust] Async webhook dispatched: id=%s decision=%s status=%d",
+                        hook.id, event.decision, resp.status_code,
+                    )
+                else:
+                    logger.warning(
+                        "[AgentTrust] Async webhook returned non-2xx: id=%s status=%d body=%r",
+                        hook.id, resp.status_code, resp.text[:256],
+                    )
+            except Exception as exc:
+                logger.warning(
+                    "[AgentTrust] Async webhook dispatch error: id=%s error=%s",
+                    hook.id, exc,
+                )
+
+    # ── Private helpers ───────────────────────────────────────────────────────
+
+    def _load_from_db(self) -> list[WebhookConfig]:
+        """Load all webhook configs from the local SQLite registry."""
+        try:
+            con = _open_db(self._db)
+            try:
+                rows = con.execute(
+                    "SELECT id, url, events, platform, name, enabled, created_at "
+                    "FROM webhooks ORDER BY created_at ASC"
+                ).fetchall()
+            finally:
+                con.close()
+        except Exception as exc:
+            logger.warning(
+                "[AgentTrust] Failed to load webhooks from DB (%s): %s",
+                self._db, exc,
+            )
+            return []
+
+        result: list[WebhookConfig] = []
+        for row in rows:
+            try:
+                events = json.loads(row[2]) if row[2] else ["all"]
+                result.append(
+                    WebhookConfig(
+                        id=row[0],
+                        url=row[1],
+                        events=events,
+                        platform=row[3],
+                        name=row[4],
+                        enabled=bool(row[5]),
+                        created_at=row[6],
+                    )
+                )
+            except Exception as exc:
+                logger.warning(
+                    "[AgentTrust] Skipping malformed webhook row id=%r: %s",
+                    row[0], exc,
+                )
+        return result
+
+
+# ---------------------------------------------------------------------------
+# Headers helper
+# ---------------------------------------------------------------------------
+
+def _webhook_headers(sdk_version: str) -> dict[str, str]:
+    return {
+        "Content-Type": "application/json",
+        "User-Agent":   f"AgentTrust-SDK-Webhook/{sdk_version}",
+        "X-AgentTrust-SDK-Version": sdk_version,
+    }
+
+
+# ---------------------------------------------------------------------------
+# TierGateWebhookError
+# ---------------------------------------------------------------------------
+
+class TierGateWebhookError(PermissionError):
+    """
+    Raised when webhook operations are attempted on a tier below Team.
+
+    Inherits ``PermissionError`` so callers can catch it with the standard
+    built-in exception hierarchy without importing this module.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Convenience builder: ValidateResponse → WebhookEvent
+# ---------------------------------------------------------------------------
+
+def event_from_response(
+    response: Any,
+    agent_id: str,
+    framework: str = "REST",
+    session_id: str | None = None,
+) -> WebhookEvent:
+    """
+    Build a ``WebhookEvent`` from a ``client.validate()`` response.
+
+    This is the bridge the ``AgentTrustClient`` uses to convert a
+    ``ValidateResponse`` into the normalised event the dispatcher expects.
+    You can also call it manually when integrating the dispatcher into
+    custom validation flows::
+
+        from agentrust_sdk.webhooks import WebhookDispatcher, event_from_response
+
+        result = client.validate(agent_id="pay-agent", user="alice", input="Pay $500")
+        dispatcher.dispatch(event_from_response(result, agent_id="pay-agent"))
+    """
+    return WebhookEvent(
+        envelope_id=response.envelope_id,
+        agent_id=agent_id,
+        decision=response.decision.outcome if response.decision else "pending",
+        risk_tier=response.risk.tier if response.risk else "unknown",
+        risk_score=response.risk.score if response.risk else 0.0,
+        session_id=session_id,
+        framework=framework,
+        sdk_version=SDK_CONFIG.sdk_version,
+    )