> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Run an agent when a webhook fires — from your app, GitHub, anywhere

A trigger runs one of your agents when an inbound webhook is hit. Create a trigger, copy its webhook URL into your app or GitHub, and every time that URL receives a POST the platform runs your agent **as you** with the request payload as input. The event-driven sibling of [Schedules](/features/schedules).

## Create a trigger

<CodeGroup>
  ```bash CLI theme={null}
  runtools trigger create \
    --agent pr-reviewer \
    --source github \
    --events pull_request \
    --message "Review this pull request."
  ```

  ```typescript SDK theme={null}
  const trigger = await rt.triggers.create({
    agent: 'pr-reviewer',
    source: 'github',            // verifies GitHub's signature
    events: ['pull_request'],    // only fire on PRs
    message: 'Review this pull request.',
  });
  console.log(trigger.webhookUrl);     // paste into GitHub
  console.log(trigger.signingSecret);  // GitHub webhook secret — shown once!
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.runtools.ai/v1/triggers \
    -H "Authorization: Bearer rt_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{"agent":"pr-reviewer","source":"github","events":["pull_request"],"message":"Review this PR."}'
  ```
</CodeGroup>

The response includes `webhookUrl` (and, for signed sources, `signingSecret`) — **shown only once.** Copy them immediately.

## Two kinds of trigger

### Custom (any app)

The default. The webhook URL carries an unguessable token — possessing the URL authorizes it (like a Slack/Zapier incoming webhook). Just POST any JSON:

```bash theme={null}
curl -X POST "https://api.runtools.ai/v1/trigger-hooks/wh_xxx" \
  -H "Content-Type: application/json" \
  -d '{"order_id":123,"status":"paid"}'
```

The whole payload is handed to the agent alongside your prompt.

### GitHub (verified)

Set `source: github`. RunTools verifies GitHub's `X-Hub-Signature-256` against your signing secret and can filter by event type. Set it up in your repo:

1. **Settings → Webhooks → Add webhook**
2. **Payload URL** = the `webhookUrl` from create
3. **Content type** = `application/json`
4. **Secret** = the `signingSecret` from create
5. Choose the events you want (matching the trigger's `events` filter)

Now opening a PR runs your agent on the PR payload — it can review, label, or comment back via the GitHub tool.

## Manage

<CodeGroup>
  ```bash CLI theme={null}
  runtools trigger list
  runtools trigger deliveries <id>          # inbound history
  runtools trigger regenerate-secret <id>   # rotate the URL/secret
  runtools trigger delete <id>
  ```

  ```typescript SDK theme={null}
  await rt.triggers.list();
  await rt.triggers.listDeliveries(id);
  await rt.triggers.regenerateSecret(id);
  await rt.triggers.update(id, { enabled: false });  // pause
  await rt.triggers.delete(id);
  ```
</CodeGroup>

## Good to know

* **Runs as you.** Fires execute with the creator's permissions, billed to your org. Credit-aware — a fire is skipped (not failed) when you're out of credits.
* **Fast ack.** The webhook returns `202` immediately and runs the agent in the background; senders that retry on non-2xx won't double-fire (GitHub deliveries dedupe on the delivery id).
* **Thread mode.** `per_fire` (a new thread per event) or `rolling` (one continuous thread).
* **Auto-disable** after repeated failures; **rotate** the secret any time (the previous URL stops working immediately).

<Tip>
  Use the **Triggers** page in the dashboard to create a trigger, copy the URL/secret once, and watch the deliveries log.
</Tip>