.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Webhooks are the fastest way to turn OpenClaw from “a chat assistant” into “a system that reacts.” Instead of waiting for you to message it first GitHub can ping it when a PR opens Stripe can ping it when a payment fails and n8n can ping it on a schedule. OpenClaw takes that inbound event and turns it into an agent run or a lightweight wake-up then routes the result back to whatever channel you actually use.
This article focuses on HTTP webhooks on the OpenClaw Gateway. There is another thing in OpenClaw that also gets called “hooks” in some docs and configs. Those are internal event hooks that run inside the Gateway when local lifecycle events fire. They’re useful too but they’re not how Stripe or GitHub talks to your server.
If your OpenClaw instance is freshly deployed on a VPS and you still do basic ops in SSH first do the boring step and make sure your gateway is stable. The OpenClaw quickstart onboarding over SSH makes that part smoother.
Two different “hooks” systems and why the naming confuses people
OpenClaw ends up with two concepts that sound similar:
- HTTP webhooks which are inbound HTTP endpoints that external services call
- Internal hooks which are local event handlers that run inside the Gateway process
If you are integrating GitHub Gmail Stripe or a home sensor you want HTTP webhooks. If you want “whenever a new session starts write a small memory file” you want internal hooks. They can be used together but they solve different problems.
What HTTP webhooks look like in OpenClaw
At the simplest level OpenClaw exposes a webhook path on the Gateway then protects it with a shared secret. External services POST JSON to that path and OpenClaw turns it into either a wake event or a full agent run.
You will usually see three categories of endpoints:
- a “wake” style endpoint that just nudges the agent
- an “agent run” style endpoint that executes a prompt and can deliver a reply to a chat channel
- custom named endpoints that you map to one of the above using templates or transforms
Even if you never write code you can get pretty far with mappings. If you do write code transforms are where you handle messy payloads and filter out noisy event types.
Enabling webhooks in configuration
Webhook configuration lives under a hooks block in your OpenClaw config. File names vary by install style but the idea is the same: enable hooks set a token and decide what URL path you want.
Here is an example config block. Treat this as a starting point not gospel. Your existing config keys might be slightly different depending on the version and how you installed.
hooks: {
enabled: true,
path: "/hooks",
token: "put-a-long-random-secret-here"
}That token is your webhook password. Don’t reuse an API key from somewhere else and don’t use something short. If you run OpenClaw as a service put it in an environment variable instead of hardcoding it in a file that gets copied around.
How webhook authentication is sent
Most setups use a Bearer token header because it’s supported by basically every webhook sender and every automation platform. The request looks like this:
Authorization: Bearer YOUR_HOOK_TOKENSome integrations use a custom header instead. If you are wiring a service that cannot set headers at all you will need an intermediary that can add headers before forwarding. Hook relays and automation tools are good at this.
Built-in webhook endpoints you will actually use
Even if you build lots of custom mappings most people end up relying on two core behaviors: “wake” and “agent run.” The naming might differ in your install but the behavior is consistent.
Wake endpoint
A wake endpoint is for events where you don’t need a response right now. You just want the agent to notice that something happened. Think of it as a tap on the shoulder.
Use it for things like “sensor changed state” or “job finished” where your workflow is already doing the heavy lifting and OpenClaw only needs to decide if the event matters or how to summarize it.
A minimal payload often includes a single text field describing the event. Some setups also support a mode that decides if the agent should wake immediately or wait until the next scheduled heartbeat.
Agent run endpoint
An agent run endpoint is for events where you want a real turn. GitHub sends a pull request event and you want OpenClaw to summarize the diff. Stripe sends a payment failure event and you want a message sent to Slack plus a short explanation of what failed.
Agent run payloads often include:
- message which is the prompt or instruction to run
- name which labels the event in logs or summaries
- deliver plus channel and to if you want the response routed somewhere specific
One practical detail: you want idempotency. Webhook senders can retry. Relays can replay. You do not want duplicate “payment failed” alerts or duplicate PR reviews. You solve this by choosing a stable session key or storing a “processed event id” somewhere then skipping repeats.
Mapped webhooks and why they are the sweet spot
Mapped webhooks are where OpenClaw becomes friendly to real integrations. Instead of forcing every sender to match one fixed payload you create a mapping so /hooks/github understands GitHub’s payload and /hooks/stripe understands Stripe’s payload.
Mappings usually do two jobs:
- convert the inbound payload into the message you want the agent to see
- decide what to do with the result such as deliver to Slack or keep it internal
Template based mappings
Template mappings are a nice start because they are readable. You match a path and build a message using a few fields from the JSON body.
hooks: {
enabled: true,
path: "/hooks",
token: "${OPENCLAW_HOOKS_TOKEN}",
mappings: [
{
id: "github-push",
match: { path: "github-push" },
action: "agent",
name: "GitHub",
messageTemplate: "GitHub push to {{body.repository.full_name}} by {{body.pusher.name}}"
}
]
}That template is intentionally boring. For production you usually add filtering so you only act on events you care about and you route the response to the right place.
Transform modules for real payloads
Templates are not enough once you need logic. Example: only react to PR opened and PR updated events and ignore “edited” events. Or route “payment_failed” to a private channel but “invoice_paid” to an accounting channel. This is where transforms are worth it.
A transform is a small JS or TS function that receives the inbound request body and returns a normalized action object. If the transform returns null you skip the event.
One important operational detail is where those transform files live. Keep them inside a dedicated directory with strict permissions and treat them as code because they are code.
If you want to do this kind of extension work a lot the skills and extension model matters. The OpenClaw skills guide is helpful because webhooks and skills often work as a pair: webhook wakes the agent then a skill fetches data runs the real operation and returns a result.
Session keys and deduplication
Webhook systems retry. Even the best ones do. That’s not a bug. It’s how they stay reliable when your server restarts or your network drops a packet.
You need one of these patterns:
- Fixed session key per integration so all GitHub events land in one “GitHub” session and you add your own dedupe by event id
- Session key per entity such as one session per pull request number or one session per ticket id
There is a security angle here. Letting the caller choose a session key sounds handy but it can also let an attacker spray data into many sessions and bloat your storage or confuse history. If your config supports restricting session keys to a prefix do that. If you do not need caller-selected keys then don’t enable it.
Real examples that match how people actually use this
GitHub pull request events
GitHub is a classic webhook source because it speaks webhook fluently and the payloads are well documented. A normal flow is:
- GitHub sends a pull request event
- OpenClaw receives it on a mapped endpoint
- OpenClaw fetches the PR diff then writes a summary and optionally comments
For the GitHub side the official webhook docs matter because event types and payload fields are not something you want to guess. GitHub webhooks documentation
If you want the “what does OpenClaw do with GitHub once it is wired” version the dedicated guide is here: OpenClaw GitHub automation for PR reviews and CI monitoring.
Web scraping alerts and change detection
Webhooks are also how scraping becomes automation instead of a one-off script. A scraper checks a page stores the result then posts a webhook to OpenClaw when something changed. OpenClaw decides if it is important then sends you one message not twenty.
If you are doing scraping with OpenClaw itself then your browser and scraping skills can be part of the workflow too. The full scraping article is here: web scraping with OpenClaw.
Stripe and payments
Stripe webhooks are a clean example because they come with built-in signature verification on Stripe’s side and a very clear event type system. If you are handling billing events you should not rely only on “a shared token.” You want to verify Stripe’s signature at the edge then forward into OpenClaw.
Stripe’s webhook docs are here and they’re worth reading once. Stripe webhooks documentation
n8n and automation platforms
Automation platforms are the duct tape layer. OpenClaw is good at reasoning and summarizing then choosing what to do next. n8n is good at holding credentials calling APIs and doing boring transforms without spending model tokens.
There are two common patterns:
Pattern A n8n triggers OpenClaw. n8n receives an event or runs on a schedule then calls the OpenClaw agent endpoint with a message like “summarize new leads” or “this build failed parse the logs snippet.”
Pattern B OpenClaw triggers n8n. OpenClaw decides an action then calls an n8n webhook to execute it. This is a good way to keep secrets out of the agent runtime and keep integrations clean.
n8n’s webhook and HTTP request nodes make this straightforward. n8n webhook node documentation
Production reliability and why raw webhooks can be annoying
Here’s the practical problem: your webhook sender fires an event but your Gateway is restarting. If the sender does not retry or the retries are short you lose the event. That is the moment people start saying “webhooks are unreliable” when the real issue is “my endpoint has no queue.”
You can harden this in a few ways:
Option 1: Use a webhook relay that stores and retries
Relays sit between GitHub Stripe and friends and your OpenClaw endpoint. They accept the webhook first store it then forward to you with retries. Many also add dedupe and dashboards so you can replay failed deliveries.
Hookdeck is a common choice in this category. Hookdeck
If you use a relay you can also solve the “some services cannot set headers” problem because the relay can add your Bearer token header on the forwarding side.
Option 2: Reverse proxy plus process manager
If you do not want a relay then put a reverse proxy in front of the Gateway. Use it for TLS termination basic filtering and rate limits. Run OpenClaw under systemd or a similar supervisor so it comes back quickly after failure. This does not give you a durable queue but it reduces downtime windows.
For VPS setups do not expose the raw gateway port directly to the internet if you can avoid it. If you need external access do it through a proxy tunnel or a tailnet. The general hosting guidance is covered in how to host OpenClaw securely on a VPS.
Security basics (don't skip)
Webhook endpoints get scanned. Not because you are special but because the internet is what it is. Treat your webhook token like a password and treat the inbound payload as untrusted input.
Keep the webhook surface small
- use long random tokens
- restrict which agents can be addressed from webhook calls if your config supports it
- avoid exposing the Gateway directly and prefer a proxy or a private network
Verify provider signatures when it matters
A shared token is a decent baseline but it is not a replacement for provider signature verification. GitHub Stripe and others can sign webhook requests. If you can verify signatures at the edge do it there then forward the clean event into OpenClaw.
Be careful with “unsafe content” toggles
Some setups allow bypassing safety wrappers for “trusted internal sources.” That can be fine for a webhook that only your own internal systems can call. Do not enable it for public webhook sources. A webhook payload can contain prompt injection attempts just like scraped web pages can.
If you are building anything serious with external triggers read OpenClaw security best practices once. It covers the same mindset you want for webhooks: least privilege and boring isolation.
Internal hooks in OpenClaw
Internal hooks are not HTTP. They are little handlers that run when OpenClaw events occur inside the Gateway. People use them for things like writing audit logs saving “session summaries” when a conversation resets injecting extra bootstrap files on startup or running a small BOOT.md routine when the gateway starts.
The structure is usually a folder with a metadata file and a handler script. The handler receives an event object then can log mutate or append messages. This is a good place to do local automation without adding a full plugin.
Internal hooks are also a decent place to implement “guardrail logging.” Example: whenever a tool runs write a short record to a log file so you can later answer “what did the agent do yesterday.”
Common webhook patterns that scale
Single ingress endpoint plus mappings
You expose one webhook base path then add mappings for each service. Your external systems call:
/hooks/github/hooks/stripe/hooks/ci/hooks/sensor
Each mapping transforms the request into either wake or agent run. This keeps your external URLs simple and your logic inside OpenClaw where you can change it without reconfiguring every service.
Two-stage processing for noisy event sources
Some sources are noisy. CI systems can send multiple events per run. Monitoring systems can spam on flapping alerts. In those cases a two-stage design works well:
Stage one is a webhook receiver that only filters and dedupes then posts a clean event to OpenClaw. Stage two is OpenClaw deciding what message to send and where.
This helps keep the agent context clean. It also keeps you from paying model tokens on events you never cared about.
