Skip to main content
Reactive routines fire in response to events rather than a schedule. Agents use them to automate workflows that should happen when something occurs — a file is created, a webhook fires, or an internal agent event is raised.

​
Trigger Types

​
Event Triggers

Internal agent events that reactive routines can listen for:
EventWhen It Fires
job.completedAny job finishes successfully
job.failedAny job reaches the Failed state
memory.writeA memory document is created or updated
routine.runAnother routine completes a run
heartbeatThe heartbeat system fires
Event triggers can filter by additional criteria. For example, a routine can listen for memory.write on a specific path: 
{
  "trigger": {
    "type": "event",
    "event": "memory.write",
    "filter": {
      "path_prefix": "inbox/"
    }
  }
}

​
Webhook Triggers

Reactive routines can expose an HTTP endpoint that fires the routine when called: 
{
  "trigger": {
    "type": "webhook",
    "path": "/hooks/deploy-complete",
    "secret": "${DEPLOY_WEBHOOK_SECRET}"
  }
}
The endpoint is available at: 
POST https://<your-ironclaw-host>/hooks/<path>
Authorization: Bearer <secret>
Webhook trigger endpoints are not yet exposed in the web gateway UI. Create webhook routines via the routine_create tool or via direct chat until UI support is added.

​
Example Webhook Request

Trigger a deploy-complete routine from a CI/CD pipeline: 
curl -X POST https://ironclaw.example.com/hooks/deploy-complete \
  -H "Authorization: Bearer ${DEPLOY_WEBHOOK_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "version": "v1.4.2",
    "commit": "abc1234"
  }'
The request body is available to the action prompt as context.

​
Guardrails

Guardrails are constraints that limit what a reactive routine can do during a single run. They are especially important for reactive routines because the trigger is external — you cannot predict how frequently events will fire. 
{
  "guardrails": {
    "max_tokens": 8000,
    "max_tool_calls": 20,
    "allowed_tools": ["memory_write", "memory_read", "memory_search"],
    "timeout_secs": 120,
    "rate_limit": {
      "max_runs": 10,
      "window_secs": 3600
    }
  }
}
GuardrailDescription
max_tokensStop the job if cumulative LLM token usage exceeds this value
max_tool_callsStop after this many tool calls
allowed_toolsWhitelist of tools the routine may use (empty = all tools allowed)
timeout_secsHard kill the job after this many seconds
rate_limit.max_runsMaximum runs within the time window
rate_limit.window_secsTime window for rate limiting (seconds)
Always set rate_limit on webhook-triggered routines. Without it, a misconfigured external service flooding your endpoint will spawn unlimited jobs.

​
Execution Context

Reactive routine jobs receive the triggering event as part of their context. For webhook triggers, this includes the request body. For event triggers, this includes the event payload (job ID, memory path, etc.). The action prompt can reference this context directly: 
action: "A job just completed: ${event.job_id}. Get the status and write a summary."