Skip to content

feat: Event formatting + smart filtering for webhook notifications #180

@nexus-marbell

Description

@nexus-marbell

Summary

Format incoming GitHub webhook payloads into human-readable swarm messages, and apply smart filtering to reduce noise (skip bots, skip internal swarm member events, surface external contributor activity).

RFC: #177 (GitHub Webhook to Swarm Notification Bridge)

Design

Events to Handle

GitHub Event Action Message Example
issues opened [GitHub] New issue #42 on finml-sage/repo by @dominik: Bug in auth
issue_comment created [GitHub] Comment on finml-sage/repo#42 by @dominik: "I found that..."
pull_request opened [GitHub] New PR #43 on finml-sage/repo by @contributor: Fix auth bug
pull_request_review submitted [GitHub] PR review on finml-sage/repo#43 by @reviewer: approved

Message Format

[GitHub] {event_description}
Repo: {owner}/{repo}
By: @{username}
Title: {title or subject}
URL: {html_url}
Preview: {first 200 chars of body, if present}

The [GitHub] prefix enables easy filtering in wake handlers and message processing.

Smart Filtering (Defaults)

Skip bot accounts:

  • dependabot[bot]
  • github-actions[bot]
  • renovate[bot]
  • Any user where type == "Bot" in the payload

Skip swarm member events:

  • If the event author is a known swarm member (based on routing config agent IDs or a configurable list), skip the notification
  • Rationale: swarm members already notify each other via swarm messages; webhook notifications for their own actions are internal noise
  • This is the "Dominik use case" -- surface activity from people OUTSIDE the swarm

Surface external contributor activity:

  • Any event from a user who is NOT a bot AND NOT a swarm member gets forwarded
  • This is the primary use case: knowing when external humans interact with our repos

Extensibility

  • Event handler pattern: each event type has its own formatter function
  • Adding new event types should require only adding a new formatter, not modifying core logic

Acceptance Criteria

  • issues.opened events produce correctly formatted swarm messages
  • issue_comment.created events produce correctly formatted swarm messages
  • pull_request.opened events produce correctly formatted swarm messages
  • pull_request_review.submitted events produce correctly formatted swarm messages
  • All messages include [GitHub] prefix
  • Bot accounts are filtered out (dependabot, github-actions, renovate, type=Bot)
  • Swarm member events are filtered out by default
  • External contributor events are forwarded
  • Message body preview is truncated to 200 characters
  • URL to the GitHub event is included in every message
  • Unhandled event types are ignored gracefully (no error, logged at debug level)
  • Unit tests cover each event type, bot filtering, member filtering, and body truncation

Dependencies

Depends on #178 (webhook endpoint provides the request handling framework).
Depends on #179 (routing config determines which agents to notify and which users are swarm members).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions