Skip to content

Event Sources — Inbound Webhook Events

Event sources allow external systems to push events into Ag2Trust, which routes them to the appropriate agent types for processing.

Overview

External System → Webhook → Event Source → Subscription Match → Agent Type → Agent

Events flow through three components:

Component Purpose
Event Source Receives inbound webhooks from a specific vendor
Event Subscription Pattern-matches events and routes them to agent types
Event Individual event record with status tracking

Supported Vendors

Vendor Event Types Example
GitHub push, pull_request.*, issue.* Code review on PR opened
Linear Issue.*, Comment.* Triage new issues
Slack message, reaction_added Respond to channel messages
Custom Any JSON payload Your own webhook events

Creating an Event Source

Event sources are scoped to a team.

  1. Go to Teams > select a team > Event Sources
  2. Click Create Event Source
  3. Configure:
  4. Name: Descriptive identifier (e.g., "GitHub PRs")
  5. Vendor: Select from GitHub, Linear, Slack, or Custom
  6. Default Agent Type: Fallback when no subscription matches
  7. Click Save
  8. Copy the generated Webhook URL and configure it in your external system (e.g., GitHub repository settings > Webhooks)

Event Subscriptions

Subscriptions define which events get routed to which agent types, using glob-style pattern matching.

Creating a Subscription

  1. Go to Teams > select a team > Event Sources > select an event source
  2. Click Add Subscription
  3. Configure:
  4. Event Pattern: Glob pattern to match (e.g., pull_request.opened)
  5. Agent Type: Which agent type should handle matched events
  6. Priority: Higher number = higher priority when multiple subscriptions match
  7. Create Task: Whether to create an AgentTask for tracking
  8. Click Save

Pattern Matching

Patterns use glob syntax:

Pattern Matches
* All events
pull_request.* All pull request events
pull_request.opened Only PR opened events
issue.created Only new issues

Priority

When multiple subscriptions match an event, the highest-priority subscription wins (higher number = higher priority).

Subscription A: pattern="pull_request.*"  priority=0   → general-review
Subscription B: pattern="pull_request.opened" priority=10  → security-review

A pull_request.opened event matches both, but Subscription B wins due to higher priority.

Task Creation

When create_task is true, Ag2Trust creates an AgentTask record that tracks the event through its lifecycle. Tasks enable:

  • Handoff between agents
  • Status tracking (open → closed)
  • Deduplication via external_ref

Event Lifecycle

Status Description
received Webhook payload stored
processing Matching subscriptions
routed Matched to an agent type
dispatched Sent to a specific agent
completed Agent finished processing
ignored No matching subscription
failed Processing error
dead Max retries exceeded

Managing Event Sources

All event source management is done through the dashboard:

  • View: Go to Teams > select a team > Event Sources to see all event sources and their status
  • Enable/Disable: Click on an event source and toggle the Enabled switch
  • Edit: Update name, vendor, default agent type, or subscriptions
  • Delete: Click Delete on an event source to remove it and all its subscriptions

Best Practices

  1. Use specific patterns — Prefer pull_request.opened over * to reduce noise
  2. Set priorities carefully — More specific subscriptions should have higher priority
  3. Enable task creation — Tasks provide audit trails and enable multi-step agent workflows
  4. Verify webhook secrets — Event source webhook secrets are KMS-encrypted; configure them in your external system for payload verification
  5. Monitor event status — Check for failed or dead events in the dashboard

Troubleshooting

Events showing as "ignored"

  • No subscription matches the event type — check your patterns
  • The event source or subscription may be disabled

Events stuck in "received"

  • The event processing background job may be delayed
  • Check that the team has running agents of the target agent type

Next Steps