Event-Driven Agents

Event-Driven vs Scheduled Agents

Scheduled agents run at fixed intervals (every hour, every night at midnight). Event-driven agents run in response to something happening: a new GitHub issue is created, a Slack message mentions the agent, a file appears in a watched directory, or a monitoring alert fires. The choice depends on your use case:

Webhook Triggers

OpenClaw exposes a webhook endpoint that external services can call to trigger agent runs. Each agent can register one or more webhook handlers that map incoming requests to agent tasks.

# agent-config.yaml
triggers:
  webhooks:
    - path: /hooks/github-pr
      secret: ${WEBHOOK_SECRET}  # HMAC signature verification
      agent: pr_reviewer
      task_template: "Review this pull request: PR #{pr_number} — {pr_title}

Diff:
{pr_diff}"
      extract:
        pr_number: "$.pull_request.number"
        pr_title: "$.pull_request.title"
        pr_diff: "$.pull_request.diff_url"

    - path: /hooks/pagerduty
      agent: incident_responder
      task_template: "Analyze this incident and suggest next steps: {incident_details}"
      extract:
        incident_details: "$.incident"

# Start OpenClaw in server mode to handle webhooks
openclaw serve --port 8080
# Webhook available at: POST http://localhost:8080/hooks/github-pr

Message Queue Consumers

For high-volume event processing or workloads that need durable message delivery and backpressure, OpenClaw can consume from message queues including SQS, RabbitMQ, and Redis streams.

triggers:
  queue:
    type: sqs
    queue_url: ${SQS_QUEUE_URL}
    region: us-east-1
    batch_size: 5             # process up to 5 messages per agent invocation
    visibility_timeout: 300   # seconds to process before message reappears
    agent: support_classifier
    task_template: "Classify and draft response for: {message_body}"

Queue-based triggers provide at-least-once delivery guarantees — messages are only acknowledged after the agent completes successfully. If the agent fails, the message becomes visible again and will be reprocessed. This makes queue-based architectures appropriate for workflows where dropped messages are unacceptable (billing events, support tickets, audit actions).

File System Watchers

For local or NFS-mounted workflows, OpenClaw can watch directories and trigger agent runs when files are created or modified. This is useful for processing uploads, monitoring log files, or triggering documentation updates when source files change.

triggers:
  filewatch:
    - path: /data/incoming
      pattern: "*.csv"
      events: [created]
      agent: data_processor
      task_template: "Process and summarize this CSV file: {file_path}"
      debounce_seconds: 2  # wait for file write to finish

Event Responses and Callbacks

Event-driven agents often need to post results back to the originating system. OpenClaw's action system lets you define post-task callbacks that run after the agent completes.

triggers:
  webhooks:
    - path: /hooks/github-pr
      agent: pr_reviewer
      on_complete:
        - action: http_post
          url: "https://api.github.com/repos/{repo}/issues/{pr_number}/comments"
          headers:
            Authorization: "Bearer ${GITHUB_TOKEN}"
          body: '{"body": "{agent_output}"}'
        - action: log
          level: info
          message: "PR #{pr_number} reviewed — {word_count} word response"

Scaling Event-Driven Agents

A single OpenClaw instance can handle modest event volumes (dozens of concurrent events), but production event-driven systems often need horizontal scaling. OpenClaw's queue-based trigger architecture supports worker scaling by running multiple OpenClaw instances consuming from the same queue:

# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: openclaw-event-worker
spec:
  replicas: 5          # 5 concurrent event-processing workers
  selector:
    matchLabels:
      app: openclaw-worker
  template:
    spec:
      containers:
        - name: openclaw
          image: ghcr.io/openclaw-ai/openclaw:latest
          args: ["serve", "--queue-only"]   # only process queue, no webhooks

Each worker processes events independently. The queue (SQS, RabbitMQ, Redis Streams) handles distribution and ensures each event is processed exactly once. This architecture scales linearly — double the workers, double the throughput. Monitor queue depth as the primary scaling signal: if the queue is growing under load, add workers.

Idempotency in Event Handlers

Event-driven systems require idempotent handlers — processing the same event twice should produce the same result without side effects. Message queues guarantee at-least-once delivery, meaning duplicate events are possible (during retries, network partitions, or redeployments).

Build idempotency into your tool implementations: check before writing (don't create a GitHub comment if one already exists for this PR and run ID), use upsert semantics for database writes, and include event IDs in all external side effects so duplicates can be detected. Store event IDs with a short TTL in Redis for deduplication when strict exactly-once semantics are required.

Monitoring Event-Driven Systems

Event-driven systems require different monitoring strategies than scheduled batch jobs. The key metrics to track are: event processing latency (time from event receipt to agent completion), queue depth (events waiting to be processed — growing queue indicates under-provisioning), error rate per event type, and agent success rate by trigger source.

OpenClaw exposes all of these via Prometheus metrics when running in server mode. A Grafana dashboard with these four metrics provides an immediately useful operational view of your event pipeline. Set alerts on queue depth exceeding 100 events and error rate exceeding 5% — these thresholds indicate when manual intervention is needed before the system falls behind or begins losing events.

# Check current queue depth
openclaw metrics --filter queue_depth
# Example output:
# openclaw_queue_depth{queue="sqs-support-tickets"} 12
# openclaw_queue_depth{queue="redis-github-events"} 0

Securing Webhook Endpoints

Webhook endpoints must be secured against spoofed requests. Always configure the secret field for webhook triggers — OpenClaw verifies HMAC-SHA256 signatures on all incoming webhooks before passing them to the agent. Reject any webhook without a valid signature immediately. For additional security, restrict webhook endpoint access by IP allowlist if your trigger source has a fixed IP range (GitHub, Stripe, and PagerDuty all publish their webhook IP ranges). Never expose webhook endpoints without authentication in production; an open webhook lets anyone trigger your agent with arbitrary content.