Event triggers

An event trigger runs an agent automatically when a specific event occurs in a connected service — for example, a new Slack mention or an opened GitHub pull request.

In the CLI and REST API, event triggers are referred to as webhook triggers. --type webhook is the value you pass when creating one.

Supported services

Service	Example events
Bitbucket	`pullrequest`, `repo`
Discord	`interaction.command`, `interaction.component`
GitHub	`pull_request`, `issues`, `push`
Jira	`issue`, `comment`
Pipedrive	`deal`, `person`
Slack	`app_mention`, `message`
Telegram	`message`
Zendesk	`ticket`

Each integration page lists its events and the actions a trigger can narrow them to. Other built-in integrations give agents tools but don’t trigger them. A custom integration can define its own events.

Create an event trigger

Open your workspace

Go to app.guild.ai and open the workspace where the agent is installed.

Go to Triggers

In the workspace’s left nav, click Triggers under Run, then click Add Trigger.

Configure the event

Select Event, choose the connected service, the event type, and an optional event action.

Select an agent

Choose the agent the trigger will run. By default, the agent receives the event as its input; see Agent input.

Name the trigger

Enter a Name, such as Nightly report. The name is required, up to 255 characters, and labels the trigger in the workspace’s Triggers list.

With the CLI

# Create a Slack event trigger
guild trigger create \
  --type webhook \
  --integration slack \
  --event app_mention \
  --agent slack-assistant

# Create a GitHub event trigger for opened pull requests
guild trigger create \
  --type webhook \
  --integration github \
  --event pull_request \
  --action opened \
  --agent code-reviewer

Agent input

Event triggers use the same agent input editor as schedule triggers. Open the Edit Trigger dialog to edit it. On desktop, a schema-driven panel appears on the right side of the dialog. On mobile, a text field appears instead. When you create a trigger for a text-input agent, the field pre-populates with a prompt template based on the integration name, event type, and action. Saving it stores it as a custom agent input. The backend default input applies only when the input is empty, for example when Pass the webhook payload unaltered is selected.

Default agent input

Without a custom input, what the agent receives depends on its input schema:

An agent that takes text, such as an llmAgent with its default schema, or an agent with no input schema, receives a prompt that names the integration, event, and action, followed by the event payload as JSON. When the event has no action, the prompt names the action as None.
An agent with a structured input schema receives the payload itself.

Bitbucket, GitHub, Jira, Slack, and Zendesk trim the payload to the fields an agent needs before delivering it. Other integrations deliver it as the service sent it.

Custom agent input

To control the input, provide a custom agent_input object when creating the trigger. It replaces the default input. Guild substitutes these placeholders anywhere in its string values:

Placeholder	Replaced with
`{webhook_event}`	The event, such as `pull_request`
`{webhook_action}`	The action, such as `opened`, or an empty string
`{webhook_payload}`	The event payload as JSON

Use custom agent input when you want to:

Add instructions or fixed settings alongside the webhook payload
Fill the fields of a structured input schema, using placeholders for the event details

guild trigger create \
  --type webhook \
  --integration github \
  --event pull_request \
  --action opened \
  --agent code-reviewer \
  --input '{"type": "text", "text": "Review this pull request and post one concise comment: {webhook_payload}"}'

Custom agent_input can also be set from the web UI when creating or editing an event trigger.

Pass the webhook payload unaltered

When you create or edit an event trigger in the web UI, select Pass the webhook payload unaltered to give the agent the default input instead of a template. Checking this option disables and clears the input editor. This option corresponds to an empty agent_input in the CLI and REST API, which gives the agent the default input.

Toggling Pass the webhook payload unaltered is non-destructive. If you uncheck it, the input editor restores the agent input template you previously entered.

Scope events with `service_config`

Use service_config to restrict event triggers to specific repositories, channels, or projects. Event triggers accept an optional service_config JSON object. When you omit it or set it to null, the trigger matches all events of the selected type (for example, every repository or every channel). Bitbucket is the exception: its triggers require workspace_slug.

Service	Field	Example	Behavior
GitHub	`repo`	`"guildaidev/guildcode"`	Only events for this repository (`owner/repo` format)
Slack	`channel_ids`	`["C01234567"]`	Only events in these channel IDs. Messages from the Slack app itself are always excluded to prevent loops.
Slack	`team_id`	`"T01234567"`	Only events from this Slack workspace, for an org-wide connection. Ignored when `channel_ids` is set.
Jira	`project`	`"ENG"`	Only events for this project key (case-insensitive)
Jira	`label_added`	`["needs-triage"]`	Only issue events where one of these labels is newly added (case-sensitive). Suppresses comment events.
Bitbucket	`workspace_slug`	`"myworkspace"`	Required. The workspace whose events the trigger receives
Bitbucket	`repo_slug`	`"myrepo"`	Only events for this repository. Without it, the webhook is installed on the workspace

service_config must be a JSON object. Do not pass an array or string at the top level. Pass service_config when you create or update a trigger with the CLI:

# GitHub: only pull requests in one repo
guild trigger create \
  --type webhook \
  --integration github \
  --event pull_request \
  --action opened \
  --agent code-reviewer \
  --service-config '{"repo": "guildaidev/guildcode"}'

# Slack: only mentions in specific channels
guild trigger create \
  --type webhook \
  --integration slack \
  --event app_mention \
  --agent slack-assistant \
  --service-config '{"channel_ids": ["C01234567"]}'

For Slack, an empty channel_ids array matches all channels. Omit service_config entirely only if you intend to process events workspace-wide.

Update an event trigger

guild trigger update <trigger-id> --event message

See Manage triggers for activating, deactivating, listing, and inspecting triggers of any type.

Identity mapping so event-started runs act as the member who caused the event
Review every new GitHub pull request for a GitHub event trigger built end to end
Answer questions when someone mentions your agent in Slack for a Slack event trigger built end to end
Draft a reply to every new Zendesk ticket for a Zendesk event trigger built end to end
guild trigger for every flag on create and update

Overview

The Smith

The Factory

Platform

Agent SDK

Event triggers

Supported services

Create an event trigger

With the CLI

Agent input

Default agent input

Custom agent input

Pass the webhook payload unaltered

Scope events with `service_config`

Update an event trigger

​Supported services

​Create an event trigger

​With the CLI

​Agent input

​Default agent input

​Custom agent input

​Pass the webhook payload unaltered

​Scope events with service_config

​Update an event trigger

​Related pages

Supported services

Create an event trigger

With the CLI

Agent input

Default agent input

Custom agent input

Pass the webhook payload unaltered

Scope events with `service_config`

Update an event trigger

Related pages