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

# Webhooks

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

Webhooks are the escape hatch. The [first-party trigger types](/cosmos/config-triggers) cover the systems Cosmos has a managed integration for. Anything else — Datadog, CircleCI, self-hosted GitLab, a service you wrote yourself — talks to Cosmos through a **custom webhook**: an HTTPS endpoint you create, paste into the source system's outbound-webhook config, and reference from a `webhook`-typed trigger.

The same JSONLogic filter machinery works on a custom webhook's payload, so the receiving Expert only wakes up for the shapes you whitelist.

## Creating a Custom Webhook

A custom webhook can be shared with your organization or kept personal, and can be reused by any number of triggers.

1. Open **Webhooks** in the sidebar (under Capabilities in settings).
2. Create a webhook: pick a type — **Bearer Token** is the generic choice — give it a description, and choose whether it's shared or personal.
3. The confirmation page reveals the **Webhook URL** and the secret (shown as the **Signing Secret**) **once** — copy both before leaving the page. The secret cannot be retrieved later. Send it as a bearer token on every request (see below).

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 from the Automations page, pick the custom webhook by name from the webhook dropdown — that wires the trigger to the URL you just minted.

## Common Webhook Examples

### Datadog — Error Alert

1. Create a webhook 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. On the **Automations** page, add a **Webhook** trigger, pick the new custom webhook from the **Webhook** 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

1. Generate a 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. On the **Automations** page, 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 open the [events log](/cosmos/manage-automations), filter by source = Webhook, and confirm the event was received.

## See Also

* [Configuring Triggers](/cosmos/config-triggers) — the full trigger reference, including event types and filters.
* [Managing Automations](/cosmos/manage-automations) — inspect captured webhook events in the events log.
* [Your First Automation](/cosmos/first-automation) — build two automations end to end.