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
Create an event trigger
1
Open your workspace
Go to guild.ai and open the workspace where the agent is installed.
2
Go to Triggers
In the left sidebar, open More and click Triggers, then click New trigger.
3
Configure the event
Select Event, choose the connected service, the event type, and an optional event action.
4
Select an agent
Choose the agent the trigger will run. By default, the agent receives the event payload as its input.
With the CLI
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 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 customagent_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
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 emptyagent_input in the CLI and REST API, which the backend treats as “forward the payload unaltered.”
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).
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:
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"}}.
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.