> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Event triggers

> Run an agent automatically when an event occurs in a connected service like Slack, GitHub, Linear, Jira, or Notion.

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.

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

## Supported services

| Service      | Example events                                |
| ------------ | --------------------------------------------- |
| Slack        | `app_mention`, `message`                      |
| GitHub       | `pull_request`, `issues`, `push`              |
| Linear       | `issue`, `comment`                            |
| Jira         | `issue_created`, `issue_updated`              |
| Azure DevOps | `workitem.created`, `git.pullrequest.created` |
| Google Docs  | Document changes                              |
| Notion       | Page updates                                  |

## Create an event trigger

<Steps>
  <Step title="Open your workspace">
    Go to [guild.ai](https://guild.ai) and open the workspace where the agent is installed.
  </Step>

  <Step title="Go to Triggers">
    In the left sidebar, open **More** and click **Triggers**, then click **New trigger**.
  </Step>

  <Step title="Configure the event">
    Select **Event**, choose the connected service, the event type, and an optional event action.
  </Step>

  <Step title="Select an agent">
    Choose the agent the trigger will run. By default, the agent receives the event payload as its input.
  </Step>
</Steps>

### With the CLI

```bash theme={null}
# 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](/platform/schedule-triggers#agent-input). 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 no input has been saved, the field pre-populates with a default based on the integration name, event type, and action.

### Custom agent input

By default, the agent receives the raw webhook payload as its input. You can override this by providing a custom `agent_input` object when creating the trigger. The custom input is merged with (or replaces) the default payload delivered to the agent.

Use custom agent input when you want to:

* Pass a fixed system prompt or configuration alongside the webhook payload
* Map specific webhook fields to a named input schema your agent expects

```bash theme={null}
guild trigger create \
  --type webhook \
  --integration github \
  --event pull_request \
  --action opened \
  --agent code-reviewer \
  --input '{"review_style": "concise", "post_comment": true}'
```

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 forward the raw webhook JSON payload directly to the agent. Checking this option disables and clears the input editor, so you do not need to define a custom input template to deliver the payload as-is.

This option corresponds to an empty `agent_input` in the CLI and REST API, which the backend treats as "forward the payload unaltered."

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

## 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).

| 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. |
| 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.    |

`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:

```bash theme={null}
# 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"]}'
```

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

## Session affinity with `session_affinity_key`

By default, Guild uses integration-specific logic to determine which session an incoming webhook event belongs to. Set `session_affinity_key` to extract the session correlation ID directly from the webhook payload instead.

`session_affinity_key` is a dot-notation path into the webhook payload. The value at that path becomes the `remote_id` that matches the event to an existing session. When the extracted value matches a prior event's `remote_id`, the agent continues in that session rather than starting a new one. When set, `session_affinity_key` overrides the integration handler's default session correlation logic.

For example, `"event.thread_ts"` extracts the Slack thread timestamp from a payload structured as `{"event": {"thread_ts": "1234567890.123"}}`.

<Note>
  If the path does not resolve — because the field is absent or an intermediate value is not an object — the trigger falls back to no affinity and starts a new session.
</Note>

## Update an event trigger

```bash theme={null}
guild trigger update <trigger-id> --event message
```

See [Manage triggers](/platform/triggers#manage-triggers) for activating, deactivating, listing, and inspecting triggers of any type.