OpenClaw Webhook Automation Guide

Webhooks turn your OpenClaw agent from something you talk to into something that reacts to the world. A payment comes in? Your agent processes it. A form gets submitted? Your agent follows up. No polling. No delays. Just instant, event-driven automation.

What Are Webhooks and Why They Matter for AI Agents

A webhook is a simple concept: when something happens in Service A, it sends an HTTP POST to Service B. No checking every 5 minutes. No wasted API calls. The event finds you.

For AI agents, this is a big deal. Instead of your agent constantly asking "did anything happen yet?", external services push events directly to it. Your Stripe account tells your agent about a new payment. Your GitHub repo tells your agent about a new issue. Your CRM tells your agent about a new lead.

OpenClaw has webhook support built into its Gateway. You enable it, set a token, and suddenly your agent can receive events from hundreds of services. No middleware. No Zapier. No extra monthly bill.

That's the part most people miss. Tools like Zapier and n8n charge per automation or per execution. OpenClaw webhooks are free, unlimited, and run on your own hardware. You're already paying for the server. The webhooks are just a config flag.

How to Set Up OpenClaw Webhook Automation

The setup takes about 2 minutes. You need two things in your OpenClaw config: enable hooks and set a secret token.

Here's the config block:

{
  hooks: {
    enabled: true,
    token: "your-secret-token-here",
    path: "/hooks"
  }
}

Once you restart OpenClaw, the webhook endpoint is live at http://your-server:port/hooks. If you're running on a VPS or Mac Mini with a public IP, external services can hit it directly. If you're behind a firewall, you'll need to either port-forward or use a tunnel like Cloudflare Tunnel.

Every request to your webhook must include the token. OpenClaw accepts it in two ways:

• Authorization: Bearer your-token (recommended)
• x-openclaw-token: your-token

Query string tokens (?token=...) are rejected for security. Good. That keeps tokens out of server logs.

If you haven't set up your API keys yet, check out the OpenClaw API key setup guide first. You need a working agent before webhooks make sense.

The Two Webhook Endpoints Explained

OpenClaw gives you two webhook endpoints. They do different things, and knowing which one to use matters.

POST /hooks/wake

This is the lightweight option. It sends a system event to your main session and optionally triggers an immediate heartbeat.

curl -X POST http://your-server:port/hooks/wake \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"text": "New order received: #4521, $89.00", "mode": "now"}'

The text field is what your agent sees. Write it like a notification. The mode field controls timing: "now" triggers your agent immediately, "next-heartbeat" waits for the regular check-in cycle.

Use /hooks/wake when you want your agent to know about something but don't need a dedicated response. Think: logging events, low-priority notifications, or feeding context for later.

POST /hooks/agent

This is the heavy hitter. It spins up an isolated agent session, runs a task, and can deliver the result to any messaging channel.

curl -X POST http://your-server:port/hooks/agent \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "New support ticket: Customer says billing page returns 404. Check the site and draft a response.",
    "name": "Support",
    "deliver": true,
    "channel": "telegram",
    "timeoutSeconds": 120
  }'

The key parameters:

Parameter	Required	What it does
message	Yes	The prompt your agent receives
name	No	Label for the session (shows in logs)
deliver	No	Send the response to a chat channel
channel	No	Where to deliver: telegram, discord, whatsapp, slack
to	No	Recipient ID (chat ID, phone number, etc.)
model	No	Override the default model for this run
timeoutSeconds	No	Max duration before the run is killed

The isolated session is important. Each webhook trigger gets its own context. It doesn't pollute your main conversation. And the result gets posted as a summary back to your main session, so you always know what happened.

Real Webhook Automation Use Cases

Here are concrete examples of webhook automations you can build today. No theory. Just real setups.

Stripe payment notifications

Stripe lets you configure webhook endpoints in your dashboard. Point it at /hooks/agent with a mapping that extracts the customer email, amount, and product. Your agent sends a personalized thank-you message or flags failed payments for follow-up.

GitHub issue triage

Set up a GitHub webhook on your repo. When a new issue is created, your agent reads the title and body, checks if it's a bug or feature request, applies labels, and posts a first response with relevant documentation links.

Form submission follow-up

Tools like Typeform, Tally, and Cal.com support webhook notifications. When someone books a call or submits a form, your agent can research the person, pull their LinkedIn profile, and prepare a briefing doc before you even open your calendar.

E-commerce order processing

Shopify, WooCommerce, and most e-commerce platforms fire webhooks on new orders, refunds, and inventory changes. Your agent can summarize daily orders, flag unusual patterns, or update your accounting spreadsheet automatically.

Email forwarding

Set up an email forwarding rule that POSTs to your webhook. Your agent reads the email, decides if it needs a response, drafts one, and sends it to your Telegram for approval. You tap "send" and you're done.

Payload Mappings for Any Service

Different services send different JSON payloads. Stripe's webhook payload looks nothing like GitHub's. OpenClaw handles this with payload mappings in your config.

A mapping tells OpenClaw how to transform an incoming payload into a wake or agent action. You define which fields to extract and how to format the message your agent receives.

For example, a GitHub issue mapping might extract action, issue.title, and issue.body, then format them into: "New GitHub issue: [title]. Description: [body]. Please triage and respond."

You can also set default delivery options per mapping. A Stripe mapping might always deliver to your Telegram. A GitHub mapping might deliver to Discord. Each mapping is independent.

This is where OpenClaw gets interesting compared to tools like Zapier or n8n. Those tools charge per "zap" or per execution. OpenClaw mappings are just config. Run 10,000 webhooks a day and you pay nothing extra.

Securing Your Webhook Setup

Webhooks are an open door into your agent. You need to lock them down.

Best practices:

• Use HTTPS. If you're running on a VPS, put Nginx or Caddy in front with a TLS certificate. Cloudflare Tunnel works too. Never send tokens over plain HTTP.
• Rotate tokens periodically. Every 90 days is reasonable. Update the sending services when you do.
• Use allowedAgentIds. Restrict which agents can be triggered via webhook. If you only need your main agent, set allowedAgentIds: ["main"].
• Set timeouts. Always include timeoutSeconds in your webhook calls. A runaway agent session from a malformed webhook shouldn't burn through your API credits for 30 minutes.
• Monitor your logs. OpenClaw logs webhook hits. Check for unexpected sources or repeated failures.

If you're running OpenClaw on a dedicated machine like a Mac Mini, you can use Cloudflare Tunnel to expose only the webhook path without opening any ports on your router. Zero attack surface on your home network.

Webhooks vs Polling vs Cron Jobs

OpenClaw gives you three ways to trigger automations. Here's when to use each.

Method	Best for	Latency	Cost
Webhooks	External events (payments, form submissions, GitHub)	Instant (sub-second)	Zero per trigger
Cron jobs	Scheduled tasks (daily reports, weekly summaries)	Fixed schedule	One API call per run
Heartbeat polling	Periodic checks (inbox, calendar, notifications)	Every 15-30 min	One API call per beat

Webhooks win when you need instant reactions to external events. Cron jobs win when you need things to happen on a schedule regardless of external triggers. Heartbeats are for casual monitoring.

The best setups combine all three. Webhooks handle real-time events. Crons handle recurring tasks. Heartbeats catch everything else.

Ready to build your first automation? Install OpenClaw and have your webhook running in under 5 minutes. If you want to see the exact webhook configs I use for my own business, I share everything inside OpenClaw Lab.