OpenClaw Engineering, Chapter 8: Event-Driven Workflows

In Chapter 7, we covered how bundled and workspace skills coexist, and how ClawHub (OpenClaw's community registry) keeps 13,000+ skills from colliding. But a critical question remains: how do workflows start? So far we've assumed a human invokes an agent—"Claude, please do X." But much of the power of autonomous agents emerges when they act without explicit invocation. An event occurs in the external world (a pull request is opened, a file is uploaded, a scheduled time arrives), and an agent springs into action automatically. This is event-driven automation, and it's the subject of this chapter. Instead of waiting for a human to say "go," the agent watches for triggers and acts when conditions are met.

Hooks: triggering on internal events

A hook is the simplest trigger mechanism in OpenClaw. You define an event type and a skill to execute when that event occurs—command events (an agent is invoked with a specific command), session events (a session starts or ends), or gateway events (the gateway loads a skill or shuts down). Hooks are synchronous, lightweight, and evaluated locally by the gateway.

The power of hooks is that they let you react to the agent's own lifecycle without writing custom code. When a session ends, a hook might log all actions taken for audit purposes. When a session starts, another hook might validate that all required credentials are set. You can chain hooks together so the first hook performs a check and the second proceeds based on the result—like a multi-step reaction to a single event.

Hooks must complete quickly—under 5 seconds is a rule of thumb. If you need heavyweight work in response to an event, use a webhook or background task instead. Also think about failure modes: should a hook failure bring down the parent operation, or should it log and proceed? OpenClaw lets you mark hooks as "critical" (failure fails the parent) or "best_effort" (failure logs but proceeds). Most hooks should be best_effort; you don't want a monitoring hook failure to crash your agent.

Webhooks: integrating external systems and CI/CD

Hooks are internal to OpenClaw. Webhooks extend this concept to the outside world: they're HTTP endpoints that external systems can call to trigger agent workflows. When a GitHub repository wants to trigger code review, it makes an HTTP POST request to your agent's webhook endpoint, including a JSON payload with relevant information. The agent receives this and executes a skill or workflow in response.

Setting up a webhook is straightforward: define a path (the HTTP endpoint), a skill to invoke, and a validation method (to ensure the request is genuine). GitHub webhooks use HMAC-SHA256 signatures to prove authenticity—the signature is computed using a secret known only to GitHub and your OpenClaw gateway. Verify the signature before processing the request. This prevents attackers from forging webhook requests.

A real-world pattern: a fintech company has a deployment process for their trading engine. Manual deployment is slow; fully automated CI/CD is risky. The solution: a webhook-triggered agent that runs comprehensive tests, performs static analysis, runs the change against a simulated market, and if all checks pass, creates a pull request for human review. Humans review and approve. Only then does deployment proceed. This hybrid approach combines agent automation with human oversight, achieving speed and safety together.

Designing idempotent webhooks

Webhooks can be delivered multiple times due to network issues. If a webhook request fails, the external system might retry. If your skill isn't idempotent, retries cause problems: duplicate emails, duplicate issues, double charges. The solution: design skills to be idempotent, or have the webhook handler check for duplicates.

For example, a webhook that creates a support ticket should check: "Has a ticket already been created for this event? If yes, return the existing ticket ID. If no, create a new one." This prevents duplicates even if the webhook is delivered twice. Include in your webhook a unique delivery ID (GitHub provides one in the X-GitHub-Delivery header), store delivered IDs in a cache, and reject any ID you've already seen.

Advanced webhook patterns

Beyond basic webhooks, there are patterns that make them more powerful. Webhook chaining: a webhook's skill output becomes input to another webhook, creating a pipeline. Conditional webhooks: a single endpoint triggers different skills based on event details (GitHub sends multiple event types; the handler checks the type and routes accordingly). Retry with exponential backoff: if a webhook skill fails transiently, retry with increasing delays (1s, 2s, 4s, 8s).

Another pattern: deadletter queues. If a webhook consistently fails, instead of dropping it or filling error logs, store it in a special queue for later analysis. A human can investigate, fix the underlying issue, and replay the failed webhook. This prevents one failing webhook from eating your resources.

TypeScript handlers for performance-critical paths

OpenClaw also supports writing custom event handlers in TypeScript—statically-typed, compiled handlers that run in the gateway runtime with high performance. While skills are the primary extension mechanism (flexible, easy to add dynamically), TypeScript handlers are useful for performance-critical event processing. If you need to process 10,000 webhook requests per second with sub-millisecond latency, TypeScript handlers might be necessary; skills might not be fast enough.

A TypeScript handler can validate, transform, and dispatch to skills efficiently. For example, a handler might parse a webhook payload, check that the push is to the main branch, and if so, invoke the CI runner skill. The handler acts as a lightweight orchestrator: simple decision logic before delegating to skills for the actual work.

Putting it all together: a real SaaS deployment webhook

Imagine you're building a SaaS platform where customers can deploy their code through a webhook. A customer sends a webhook with their code, and the entire deployment pipeline runs: clone, install, build, test, stage, verify, deploy to production, monitor. Some steps run in parallel; others are sequential.

The webhook endpoint validates the signature using the customer's secret, checks that the deployment token is valid, and ensures the customer is authorized. If all checks pass, it invokes a Lobster workflow (OpenClaw's deterministic orchestration language, covered in the next chapter) with the deployment parameters. The workflow handles the entire pipeline explicitly: if code doesn't clone, fail immediately. If tests fail, don't deploy. If production deployment fails, automatically rollback and alert.

Status updates are sent back to the customer via webhook callback at each stage: "deployment started," "tests passed," "deployed to staging," etc. The customer tracks progress in real-time. This architecture demonstrates best practices: webhooks integrate external systems, skills validate and route requests, and workflows orchestrate complex multi-step processes with explicit error handling. The entire system is observable, auditable, and resilient.

What's next

Event-driven workflows respond to external stimuli, but much of the automation world operates on schedules: run this every night at 2 AM, check this every hour, process this queue every 5 minutes. Chapter 9 covers time-based automation through cron jobs and the Lobster workflow engine—deterministic, resumable, approval-gated orchestration that handles the full spectrum from simple scheduled tasks to complex multi-step pipelines.