Wake an agent from incoming events

An event trigger gives an agent a task when another service sends an event. GitHub offers PR merged and Release published presets. Other services can use Generic webhook. Results appear in the agent's existing conversation. The agent keeps its configured permissions, approval rules, model policy, and daily budget.

If you see Event triggers under Autonomy, you can configure incoming events for this agent.

Who can set this up

Source setup requires permission to manage workspace connectors. Trigger changes require a workspace administrator who can edit the agent. You also need permission to configure webhooks on the GitHub repository.

A repository event does not grant access to repository contents. Connect an appropriate GitHub account separately if the agent needs to inspect private code or checks.

Event work applies the stricter no-training preferences of the trigger creator and the agent owner, together with organization requirements. A repository event cannot relax those choices.

Create an event trigger

Open the agent's settings and select Autonomy. Under Event triggers, select Source setup to connect a service. Sources are shared within the workspace. Select New trigger, choose a source, and write the instructions the agent should follow.

An agent can have up to 20 event triggers, including disabled triggers. Delete a trigger to make room for another.

Each trigger saves separately from the daily budget and pause settings. Existing triggers keep their source and event preset. Create another trigger to change either.

Connect GitHub

1. In Source setup, select GitHub.
2. Select an existing GitHub connection, or select Connect GitHub and complete authorization.
3. Choose a repository where your connection has administration access.
4. Select Create source and save the signing secret securely.
5. Select Install GitHub webhook.
6. Select Check verification after GitHub sends its verification ping.

For manual setup, enter the repository as owner/repository and create the source. Copy its URL and signing secret into GitHub's repository Settings → Webhooks → Add webhook. Choose application/json, enable Pull requests and Releases, and keep SSL verification on.

Create a trigger using PR merged or Release published. A PR trigger can match a Base branch. Release triggers exclude prereleases unless you select Include prereleases. Closing an unmerged PR, creating a draft release, or editing a release does not match these presets.

Connect another service

1. In Source setup, select Generic webhook.
2. Enter a Source name and select Authentication.
3. Select Create source and save the secret securely.
4. Configure your service to send a JSON object to the displayed webhook URL.
5. Create a trigger for that source and send a test event from your service.

With Bearer token, send Authorization: Bearer <token>. With HMAC-SHA256, send X-Webhook-Signature: sha256=<hex digest>. Calculate that digest over the exact request body using the signing secret. The secret is shown once, when you create the source.

An optional Event name filter selects events by name. Bearer authentication uses X-Webhook-Event, then the JSON event field, or type when event is absent. HMAC authentication uses the signed JSON event or type field. A conflicting header is rejected. Leave the filter empty to accept any event from the source.

For example, a build service can send:

{
  "event": "build.failed",
  "title": "Build 123 failed",
  "url": "https://builds.example.com/runs/123",
  "result": "failed"
}

Use an Event name of build.failed and instructions such as "Inspect this build failure and propose a fix."

Send a stable X-Webhook-Id when retrying the same event. A retry with the same ID and content does not create another agent delivery. Reusing that ID for different content returns 409. With bearer authentication, each request without this header is a new event. HMAC authentication also rejects replay of an identical signed body, even with another header ID. Include a unique event ID or timestamp inside the JSON body when separate HMAC events otherwise have identical content.

Generic payloads can be at most 16 KiB. Each source accepts at most 120 new requests per minute. A 429 response includes a Retry-After header. Retry the same event ID after that delay.

Your sender must support the selected authentication headers. If it cannot, use an adapter that authenticates and forwards its events. Native provider signature formats other than GitHub's are not supported by the generic HMAC option.

Webhook setup lets a service send events. Connect its tools separately if the agent needs to read data or take actions there. Do not include credentials in payloads or trigger instructions.

Check the result

A successful webhook response confirms receipt of the event; it does not confirm that the agent finished its task. Delivery history distinguishes waiting work, work sent to the agent, completion, failure, and skipped events. Open the agent conversation to review the result and any approval requests.

Disabled sources or triggers stop new event work. Paused, inactive, or budget-limited agents skip matching deliveries. These skipped events do not automatically run when you resume the agent. You can ask the agent to inspect the relevant PR or release directly.

Changing instructions applies to future events. A received event keeps the instructions saved when it arrived. Disabling a trigger stops new event work from reaching the agent. Disabling a source or trigger also stops events that have not started. Work already running can continue.

If a delivery fails

Open Source setup → Request history to inspect authenticated requests. A filtered request did not match an enabled trigger. Its reason can identify an event-name mismatch, branch mismatch, or excluded prerelease.

If no request appears, check the sender’s delivery log, webhook URL, authentication, JSON format, and source enabled state. For GitHub, also check the exact repository and selected webhook events.

For a skipped or failed agent task, check the agent's pause state, enabled trigger, daily budget, credits, and model availability. Review the conversation before asking the agent to run the task again.