Triggers

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.

Create a trigger

runtools trigger create \
  --agent pr-reviewer \
  --source github \
  --events pull_request \
  --message "Review this pull request."

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!

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."}'

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:

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:

Settings → Webhooks → Add webhook
Payload URL = the webhookUrl from create
Content type = application/json
Secret = the signingSecret from create
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

runtools trigger list
runtools trigger deliveries <id>          # inbound history
runtools trigger regenerate-secret <id>   # rotate the URL/secret
runtools trigger delete <id>

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);

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

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

Getting Started

Platform

Core Features

Advanced

Create a trigger

Two kinds of trigger

Custom (any app)

GitHub (verified)

Manage

Good to know

​Create a trigger

​Two kinds of trigger

​Custom (any app)

​GitHub (verified)

​Manage

​Good to know

Create a trigger

Two kinds of trigger

Custom (any app)

GitHub (verified)

Manage

Good to know