Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt

Use this file to discover all available pages before exploring further.

Use a trigger to wire an external event source to an Expert. When the event fires, Cosmos starts a session on that Expert and feeds it the event payload as the activation message. Add and edit triggers from the Triggers section of the Expert editor.

​
Supported Trigger Types

TypeWhen to use
WebhookAny service that can POST JSON to an HTTPS URL. Authenticated with a one-time bearer secret.
GitHubGitHub repository events (PRs, issues, pushes, comments, reviews).
LinearLinear issue/comment events.
SlackSlack mentions/messages/events.
PagerDutyPagerDuty incident events.
ScheduledCron schedule (see Schedules).
For GitHub, Slack, and Linear triggers, connect the integration once from Configuration → Integrations — Cosmos owns the upstream URL registration. PagerDuty triggers reference a PagerDuty integration routing key directly. For any other source — including GitLab and Jira — use a Webhook trigger backed by a custom webhook URL you mint from Configuration → Webhooks (see below).

​
Adding a Trigger to an Expert

  1. Open Experts in the sidebar and click the Expert you want to wire up (or click + Create Expert).
  2. Scroll to the Triggers section and click + Add Trigger.
  3. Fill in:
    • Name — a human-readable label (e.g. on-pr-opened).
    • Type — pick from the list above.
    • Event type — for GitHub / Linear / Slack triggers, the provider event name (e.g. pull_request, Issue, app_mention).
    • Filter — an optional JSONLogic expression evaluated against the raw event payload. The trigger fires only when this expression returns true.
    • Auto-archive sessions created by this trigger — toggle off when you want to keep trigger-launched sessions visible after they go idle (useful for revisitable agent-driven sessions like a PR-author).
  4. Click Save.
The trigger type is fixed once a trigger is created. To change it, delete the trigger and add a new one.

​
Custom Webhooks

A Webhook trigger references a custom webhook URL you mint separately. Each custom webhook is shared across an organization and can be reused by any number of triggers. To mint a custom webhook:
  1. Go to Configuration → Webhooks in the sidebar.
  2. Click + Create webhook and pick a webhook flavor:
    • Bearer — generic JSON POSTs from arbitrary services (Datadog, CircleCI, custom scripts).
    • GitLab — payloads from a GitLab project.
    • Jira — payloads from a Jira automation rule.
  3. Give it a description, then click Create.
  4. The dialog reveals the trigger URL and the bearer secret once — copy both before closing the dialog. The secret cannot be retrieved later.
The trigger URL has the form: 
POST https://{tenant}.api.augmentcode.com/webhooks/{webhook_id}
Authorization: Bearer <bearer-secret>
Content-Type: application/json
The full raw HTTP body is forwarded to Cosmos as the event payload with no wrapping. When you add the Webhook trigger in the Expert editor, pick the custom webhook by name from the Webhook dropdown — that wires the trigger to the URL you just minted.

​
Payload Filters

The Filter field on a trigger is a JSONLogic expression evaluated against the parsed JSON payload. Common examples: 
// Only PR opens
{"==": [{"var": "action"}, "opened"]}

// PRs targeting main
{"==": [{"var": "pull_request.base.ref"}, "main"]}

// Comments mentioning @auggie
{"in": ["@auggie", {"var": "comment.body"}]}

// Severity P0 or P1
{"in": [{"var": "severity"}, ["P0", "P1"]]}
To test a filter against real events your integrations have already received, go to Configuration → Events log, filter by source / event type, and inspect the payload. The Events log is the source of truth for what your triggers actually see — use it to capture real shapes before writing filters.

​
Common Trigger Examples

​
PagerDuty — P1 Incident Triggered

PagerDuty triggers route by integration key rather than event type. Create a PagerDuty Events API v2 integration on the relevant service, copy its routing key, and paste it into the PagerDuty routing key field on the trigger. Use the Filter field to match specific incident actions: 
{"and": [
  {"==": [{"var": "event.event_type"}, "incident.triggered"]},
  {"in": [{"var": "event.data.priority.summary"}, ["P1"]]}
]}

​
Datadog — Error Alert (Custom Webhook)

  1. Mint a Bearer webhook from Configuration → Webhooks and copy the URL + bearer secret.
  2. In Datadog → Integrations → Webhooks, configure a custom webhook with the trigger URL and add Authorization: Bearer <bearer-secret> under Custom Headers.
  3. In your Expert, add a Webhook trigger, pick the new custom webhook from the dropdown, and set Filter to match the alerts you care about: 
    {"and": [
  {"==": [{"var": "alert_type"}, "error"]},
  {"in": [{"var": "priority"}, ["P1", "P2"]]}
]}

​
CircleCI — Workflow Failed (Custom Webhook)

  1. Mint a Bearer webhook the same way.
  2. In CircleCI → Project Settings → Webhooks, configure a webhook with the trigger URL and add Authorization: Bearer <bearer-secret> under headers.
  3. In your Expert, add a Webhook trigger pointing at the new custom webhook with Filter: 
    {"and": [
  {"==": [{"var": "type"}, "workflow-completed"]},
  {"==": [{"var": "workflow.status"}, "failed"]}
]}

​
Test Any Custom Webhook with curl

You can fire a test event into any custom webhook with curl: 
curl -X POST "https://${TENANT}.api.augmentcode.com/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer ${WEBHOOK_BEARER_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"action": "ping", "message": "hello from curl"}'
Then go to Configuration → Events log and filter by source = Webhook to confirm the event was received and inspect the parsed payload.