PR #18042: feat(gateway): per-route sender and event-type denylists for webhook routes

• Repository: NousResearch/hermes-agent
• Author: seanedwards
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/18042

Description (problem / solution / changelog)

Closes #18041.

Summary

Adds optional ignored_senders and ignored_event_types keys to webhook route config so a system-wide Forgejo/Gitea/GitHub firehose can drop noisy events (status, push, dependabot, etc.) without invoking the agent. Also recognizes X-Gitea-Event and X-Forgejo-Event headers alongside the existing GitHub/GitLab detection.

Filtered events return 200 {filtered: true, reason, ...} so the source treats the request as successful and won't retry. Both new keys default to empty — fully backward-compatible.

Example

platforms:
  webhook:
    extra:
      routes:
        forgejo-firehose:
          secret: ${FORGEJO_WEBHOOK_SECRET}
          ignored_event_types: [status, push, watch, star]
          ignored_senders: [dependabot, forgejo-actions, mirror-sync-bot]
          prompt: ...

Design notes

• Allowlist still wins. The existing events: allowlist runs first (returning {status: ignored}), then the new denylists run (returning {filtered: true, ...}). This preserves backward compatibility and gives different response shapes for "config rejected this" vs "denylist filtered this," which helps when debugging overlapping configs.
• Sender extraction is defensive. sender.login isn't formally documented as present on every Forgejo/Gitea event type, so a missing/non-dict sender falls through to dispatch rather than getting silently dropped.
• Case-insensitive exact match. No glob/regex (YAGNI). Easy to add later if needed.
• Filter placement. At the existing event-type filter seam (after auth, signature validation, parse, rate-limit). Keeps the change minimally invasive. One known consequence: filtered events count against the route's rate limit; the lever is the rate_limit config if it bites.

Test plan

• 9 new unit tests in tests/gateway/test_webhook_adapter.py::TestDenylistFilters — both filters, case-insensitivity, missing-sender defensive default, allowlist precedence, Forgejo/Gitea header detection, backward compat
• All 45 webhook-adapter tests pass; 27 related webhook integration/dynamic-route/signature tests still pass
• Tested on Linux (Fedora 43, Python 3.12). Pure dict/string logic — no platform-specific behavior, no file I/O, no process management
• Manual: configure a route with denylists, fire curl with various Forgejo payloads, confirm 200 {filtered: true} and no agent dispatch on hits, normal dispatch on misses

Out of scope (intentional)

• Glob/regex sender matching — exact match covers the stated use case
• Reordering the rate-limit step relative to the filter — keeping the change minimal
• Startup-time schema validation for unknown route keys (e.g. typo'd ignored_sender singular silently no-ops) — worth a separate small PR

Files

• gateway/platforms/webhook.py — header detection (Gitea/Forgejo) + two denylist checks at the existing filter seam
• tests/gateway/test_webhook_adapter.py — TestDenylistFilters class with 9 tests
• website/docs/user-guide/messaging/webhooks.md — route-properties table updated; filter response shape documented

🤖 Generated with Claude Code

Changed files

• gateway/platforms/webhook.py (modified, +43/-0)
• tests/gateway/test_webhook_adapter.py (modified, +226/-0)
• website/docs/user-guide/messaging/webhooks.md (modified, +5/-1)