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

# Using Webhooks as Triggers

> Wire any external event source to a Cosmos Expert using a custom webhook trigger — receive JSON payloads and filter them with JSONLogic expressions.

A **trigger** is how an outside event reaches an Expert. When it fires, Cosmos opens a session and drops the raw event payload in as the first message. Add and edit triggers from the **Triggers** section of the Expert editor.

## Supported Trigger Types

| Type          | When to use                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------- |
| **Webhook**   | Any service that can POST JSON to an HTTPS URL. Authenticated with a one-time bearer secret. |
| **GitHub**    | GitHub repository events (PRs, issues, pushes, comments, reviews).                           |
| **Linear**    | Linear issue/comment events.                                                                 |
| **Slack**     | Slack mentions/messages/events.                                                              |
| **PagerDuty** | PagerDuty incident events.                                                                   |
| **Scheduled** | Cron schedule (see [Schedules](/cosmos/config-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](https://jsonlogic.com) 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**.

<Note>The trigger **type** is fixed once a trigger is created. To change it, delete the trigger and add a new one.</Note>

## 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 create a custom webhook:

1. Go to **Configuration → Webhooks** in the sidebar.
2. Click **+ Create webhook**.
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](https://jsonlogic.com) expression evaluated against the parsed JSON payload. Common examples:

```json theme={null}
// 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:

```json theme={null}
{"and": [
  {"==": [{"var": "event.event_type"}, "incident.triggered"]},
  {"in": [{"var": "event.data.priority.summary"}, ["P1"]]}
]}
```

### Datadog — Error Alert (Custom Webhook)

1. Create 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:

   ```json theme={null}
   {"and": [
     {"==": [{"var": "alert_type"}, "error"]},
     {"in": [{"var": "priority"}, ["P1", "P2"]]}
   ]}
   ```

### CircleCI — Workflow Failed (Custom Webhook)

1. Generate 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**:

   ```json theme={null}
   {"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:

```bash theme={null}
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.