Webhook Triggers

Webhook triggers let your agents react to real-time events from external services. When an event occurs --- a new email arrives, a GitHub issue is opened, a Slack message is posted --- the webhook fires and starts a new agent session with the event payload and your configured instructions.

How webhook triggers work

Webhook triggers are built on top of Connected Accounts. When you connect a service (like Gmail, GitHub, or Slack) to your agent, that connection can be used to subscribe to events from that service.

The flow works like this:

1. Your agent (or you, through the agent) creates a webhook trigger, specifying which event type to listen for and what instructions to run when the event fires.
2. Superagent registers the trigger with the external service through the platform proxy.
3. When the event occurs, the platform receives the webhook payload and delivers it to your Superagent instance.
4. Superagent starts a new agent session, passing the event payload along with your configured prompt.
5. The agent processes the event and takes whatever action the prompt describes.

Creating a webhook trigger

From the agent conversation

Agents can set up webhook triggers using a set of MCP tools:

1. get_available_triggers --- Lists the event types available for a connected account. For example, a Gmail connection might offer GMAIL_NEW_EMAIL, while a GitHub connection offers GITHUB_PULL_REQUEST_EVENT.

2. setup_trigger --- Creates a new webhook trigger with the following parameters:

3. list_triggers --- Lists all active webhook triggers for the agent.

4. cancel_trigger --- Removes a webhook trigger by ID.

For example, you might tell your agent: "Watch my Gmail for new emails from my manager and summarize them in Slack." The agent would use get_available_triggers to discover available Gmail events, then setup_trigger to subscribe to GMAIL_NEW_EMAIL with appropriate instructions.

From the UI

Webhook triggers appear in the Triggers section on your agent's home page alongside scheduled tasks. You can view trigger details, pause, resume, or delete them from there.

Event payload handling

When a webhook fires, the event payload is included in the agent's prompt as a JSON code block. The trigger's configured prompt is prepended, giving the agent both context and data:

Your configured prompt here.

---

Webhook payload:
```json
{
  "sender": "jane@example.com",
  "subject": "Q3 Report",
  "snippet": "Please review the attached..."
}

If multiple events arrive at the same time for the same trigger, they are batched into a single session to avoid spawning redundant work:

Your configured prompt here.

---

Event 1:
```json
{ ... }

Event 2:

{ ... }

Trigger lifecycle

Webhook triggers have four possible statuses:

Pause and resume

Pausing a webhook trigger is useful when you want to temporarily stop the agent from reacting to events without losing the trigger configuration. When paused:

• The upstream event subscription remains active (events still flow to the platform).
• Events are acknowledged and discarded instead of spawning agent sessions.
• Resuming immediately restores normal behavior --- new events will fire the agent again.

This differs from cancelling, which permanently removes both the local trigger and the upstream subscription.

Managing triggers

From the trigger detail view you can:

• Pause / Resume --- Toggle whether incoming events fire the agent or are silently discarded.
• Edit Instructions --- Update the prompt that is sent alongside event payloads.
• Delete --- Permanently cancel the trigger and clean up the upstream subscription.
• View Run History --- See every session that was started by this trigger, with links to review what the agent did.

Runtime overrides

Each trigger can override the global model and effort level, just like scheduled tasks. This is useful for tuning cost and performance per trigger:

• A high-volume, low-stakes trigger (e.g. logging new commits) might use a lighter model and low effort.
• A critical trigger (e.g. security alerts) might use the strongest model at high effort.

Set these during trigger creation via the model and effort parameters, or update them from the trigger detail view. Set a field to null to revert to the global default.

Session tracking

Each time a trigger fires, it creates a new agent session that is tagged with:

• The webhook trigger ID
• The trigger name
• An isWebhookExecution flag

The trigger detail view shows a complete history of all sessions spawned by that trigger, including whether each session is still active. The trigger also tracks a cumulative fire count and the timestamp of the last firing.

Platform connection requirement

Webhook triggers require an active connection to the Superagent platform. The platform proxy handles:

• Registering trigger subscriptions with external services
• Receiving inbound webhook payloads
• Delivering events to your local Superagent instance via real-time subscriptions

If the platform connection is unavailable, active triggers will not receive events. The UI displays a warning when the platform connection is missing.

Webhook triggers also require platform-managed service connections (Connected Accounts). If you are using a personal API key for a service provider instead of the platform-managed connection, triggers for that provider will not fire.

Common use cases

• Email triage --- React to new emails by summarizing, categorizing, or drafting replies.
• Repository monitoring --- Respond to pull requests, issues, or deployments on GitHub.
• Notification routing --- Forward or transform notifications from one service to another.
• Data pipeline triggers --- Kick off agent workflows when new data appears in a connected service.
• Incident response --- Automatically investigate alerts from monitoring services.