Skip to main content
Webhook triggers are a planned feature. The database schema exists but the webhook management API is not yet built. RunTools currently receives webhooks from WorkOS and Stripe internally.

​
Overview

Trigger agents automatically when external events occur — GitHub PRs, Stripe payments, custom webhooks, and more.
Triggers vs Tools: Triggers are inbound — external events that start your agent. Tools are outbound — actions your agent takes during execution. For example, a GitHub trigger starts your agent when a PR opens, while the GitHub tool lets your agent create PRs. Connecting a service enables both.
Configure triggers in the dashboard or via SDK/CLI — both stay in sync.

​
Quick Start

Every trigger gives you a webhook URL. Point any service at it: 
const trigger = await rt.triggers.create({
  deployment: 'my-agent',
  source: 'webhook',
});

console.log(trigger.webhookUrl);
// → https://api.runtools.ai/v1/triggers/abc123/invoke
Use this URL with any service that supports webhooks — Stripe, GitHub, Shopify, Linear, Vercel, Supabase, or your own backend.

​
Native Integrations

For common services, we handle authentication and event filtering: 
// GitHub — auto-configured via OAuth
const trigger = await rt.triggers.create({
  deployment: 'code-reviewer',
  source: 'github',
  events: ['pull_request.opened', 'pull_request.synchronize'],
  repo: 'myorg/myrepo',
  message: 'Review this PR: {{payload.pull_request.html_url}}',
});

// Stripe — uses your connected Stripe account
const trigger = await rt.triggers.create({
  deployment: 'order-processor',
  source: 'stripe',
  events: ['invoice.paid', 'charge.succeeded'],
  message: 'Process payment {{payload.id}}',
});

// Slack — uses your Slack app
const trigger = await rt.triggers.create({
  deployment: 'slack-bot',
  source: 'slack',
  events: ['app_mention'],
  message: 'Respond to: {{payload.event.text}}',
});

Connect Services

Set up triggers visually in the dashboard

​
Generic Webhook

For any other service, use the generic webhook: 
const trigger = await rt.triggers.create({
  deployment: 'data-processor',
  source: 'webhook',
  message: 'Process incoming data: {{payload}}',
});
Then configure the external service to POST to your trigger URL.

​
Managing Triggers

// List triggers
const triggers = await rt.triggers.list();

// Pause trigger
await trigger.pause();

// Resume trigger
await trigger.resume();

// Delete trigger
await trigger.delete();

// View trigger runs
const runs = await rt.runs.list({
  triggerId: trigger.id,
});

​
Custom Webhook Usage

Send POST requests to your webhook URL: 
curl -X POST https://api.runtools.ai/v1/triggers/abc123/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "event": "new_order",
    "orderId": "12345",
    "amount": 99.99
  }'
The payload is available in your agent’s context.

​
Security

​
Webhook Signatures

Verify webhook authenticity: 
const trigger = await rt.triggers.create({
  deployment: 'my-bot',
  source: 'webhook',
  secret: 'my-webhook-secret',  // Optional
});

// Requests must include X-Webhook-Signature header
// HMAC-SHA256 of body with secret

​
IP Allowlist

Restrict webhook sources: 
const trigger = await rt.triggers.create({
  deployment: 'my-bot',
  source: 'webhook',
  allowedIps: ['192.168.1.0/24', '10.0.0.1'],
});

​
Best Practices

Don’t trigger on all events. Be specific to reduce noise.
Use webhook signatures to verify request authenticity.
Set up retry logic and failure notifications.
Test triggers with sample payloads before going live.