OpenClaw Webhook Triggers: Event-Driven Automation

+15 Mana ✨
OpenClaw Webhooks Guide(DOCUMENTATION)OpenClaw Event Processing(DOCUMENTATION)

Introduction

Webhooks allow external services to push events into your OpenClaw agent in real time. Instead of polling for changes, your agent reacts instantly when something happens in the outside world. This lesson explains how webhooks work in OpenClaw, how webhook sessions are created, and the session key format that identifies each webhook connection.

Key Concepts

  • Webhook: An HTTP endpoint that external services call to deliver event data to your OpenClaw agent
  • Webhook Session Key: A unique identifier in the format hook:<uuid> that ties incoming webhook requests to a specific agent session
  • Event Payload: The JSON data that the external service sends to the webhook endpoint
  • Webhook Registration: The process of configuring an external service to send events to your OpenClaw webhook URL
  • Real-Time Processing: Events are delivered immediately when they occur, unlike polling which checks periodically

Real World Context

A development team wants their OpenClaw agent to respond to GitHub pull request events. When a PR is opened, the agent should automatically review the code and post comments. Instead of polling the GitHub API every few minutes, they register an OpenClaw webhook URL in their GitHub repository settings. Now, the moment a PR is opened, GitHub pushes an event to the webhook and the agent starts its review within seconds.

Deep Dive

Webhooks in OpenClaw are managed through the CLI and configuration. When you create a webhook, OpenClaw generates a unique URL that external services can call:

bash
openclaw webhooks create --name "github-prs" \
  --agent "code-reviewer"

This command creates a webhook named github-prs and routes incoming events to the code-reviewer agent. OpenClaw returns a URL like https://your-gateway.example.com/hooks/abc123 that you register with the external service.

Webhook Session Keys

Each webhook connection is identified by a session key in the format hook:<uuid>:

json
{
  "sessionKey": "hook:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "webhookName": "github-prs",
  "agentId": "code-reviewer",
  "createdAt": "2026-02-20T10:00:00Z"
}

This session key uniquely identifies the webhook session. When GitHub sends an event to the webhook URL, OpenClaw looks up the session key, finds the associated agent, and creates a new turn in that session to process the event.

Event Processing Flow

When an external service calls the webhook endpoint, the following sequence occurs:

bash
# 1. External service sends POST request to webhook URL
# POST https://your-gateway.example.com/hooks/abc123
# Body: { "action": "opened", "pull_request": { ... } }

# 2. OpenClaw resolves the webhook to its session key (hook:<uuid>)
# 3. The event payload is delivered to the agent as a new message
# 4. The agent processes the event and takes action

This flow is entirely push-based. The agent does not need to poll for events. The external service initiates the interaction by calling the webhook endpoint, and OpenClaw handles routing the event to the correct agent session.

Listing and Managing Webhooks

You can list all registered webhooks and their status:

bash
openclaw webhooks list

This shows all webhooks with their names, session keys, target agents, and the number of events received. You can delete a webhook when it is no longer needed:

bash
openclaw webhooks delete github-prs

This removes the webhook and invalidates its URL. Any future calls from the external service will receive a 404 response.

Common Pitfalls

  • Exposing webhook URLs without authentication: Anyone who knows the URL can send events to your agent. Use webhook secrets or HMAC signatures to verify the sender's identity.
  • Not handling duplicate events: External services sometimes retry failed deliveries, sending the same event multiple times. Design your agent to handle idempotent processing.
  • Forgetting to update webhook URLs after Gateway migration: If you move your Gateway to a new host, all webhook URLs change and external service configurations must be updated.

Best Practices

  • Use HMAC signature verification to ensure webhook events come from the expected sender.
  • Log all incoming webhook events for debugging and audit purposes.
  • Set up health check endpoints so external services can verify your webhook is reachable before sending real events.

Summary

  • Webhooks provide real-time event delivery from external services to your OpenClaw agent
  • Each webhook has a session key in the format hook:<uuid> that identifies the connection
  • Events are processed immediately as push-based interactions, not polling
  • Webhook URLs are generated by OpenClaw and registered with external services
  • Always verify webhook authenticity and handle duplicate events gracefully
✓ Completed