Tutorial
Real-Time Automation: OpenClaw webhooks enable external systems to trigger your AI agent in real-time, creating powerful automation workflows.
What Are OpenClaw Webhooks?
Webhooks allow external services to send HTTP requests to your OpenClaw instance, triggering actions or responses. This enables real-time integrations with:
- GitHub (push, PR, issues)
- CI/CD systems (build status, deployments)
- Monitoring tools (alerts, incidents)
- Custom applications
Setting Up Webhooks
1. Enable the Webhook Server
openclaw config set webhook.enabled=true
openclaw config set webhook.port=8080
openclaw config set webhook.path="/webhook"
2. Configure Security
openclaw config set webhook.secret="your-secret-key"
Webhook Event Types
Message Events
Send messages directly to OpenClaw:
curl -X POST http://localhost:8080/webhook \
-H "Content-Type: application/json" \
-H "X-Webhook-Secret: your-secret-key" \
-d '{
"type": "message",
"text": "Build #1234 failed. Please investigate."
}'
Command Events
Trigger specific commands:
{
"type": "command",
"command": "/status",
"args": ["--verbose"]
}
Building Webhook Handlers
GitHub Integration Example
Create a skill that handles GitHub webhook events:
// skills/github-webhook.ts
export async function handleGitHubWebhook(event: GitHubEvent) {
switch (event.action) {
case 'push':
await notifyNewCommits(event);
break;
case 'pull_request':
await handlePR(event);
break;
case 'issues':
await handleIssue(event);
break;
}
}
Best Practices
- Always use secrets to verify webhook authenticity
- Implement retry logic for failed deliveries
- Validate payloads before processing
- Use async processing for long-running tasks
- Log all events for debugging
Troubleshooting
Webhook Not Received
- Check firewall settings allow inbound traffic
- Verify the webhook URL is accessible
- Check OpenClaw logs for errors
Invalid Signature Errors
- Ensure the secret matches in both systems
- Check the signature header name is correct