openclaw webhooks: Webhook Configuration Guide

Webhook Overview

Webhooks are the core mechanism for OpenClaw to communicate with external platforms. Channel platforms (Telegram, Discord, etc.) push user messages to OpenClaw via webhooks, and OpenClaw can also configure outbound webhooks to push events to external systems.

View Webhook List

openclaw webhooks list

Webhooks:
  Inbound:
    /webhook/telegram     ✓ Active    telegram-main
    /webhook/discord      ✓ Active    discord-dev
    /webhook/slack        ✗ Inactive  slack-team

  Outbound:
    event-logger          ✓ Active    https://log.example.com/events
    backup-bot            ✓ Active    https://backup.example.com/messages

Inbound Webhooks (Channel Receiving)

Inbound webhooks receive message pushes from channel platforms.

View Inbound Webhook Details

openclaw webhooks show telegram

Webhook: telegram
  Path: /webhook/telegram
  Full URL: https://gateway.example.com/webhook/telegram
  Channel: telegram-main
  Status: Active
  Signature Verification: enabled
  Last Received: 2 minutes ago
  Messages Today: 230

Set Up an Inbound Webhook

# Telegram
openclaw webhooks set-inbound telegram \
  --url "https://gateway.example.com/webhook/telegram" \
  --verify-signature

# Discord
openclaw webhooks set-inbound discord \
  --url "https://gateway.example.com/webhook/discord" \
  --public-key "discord-public-key"

Test an Inbound Webhook

openclaw webhooks test telegram --inbound

This sends a test request to the webhook URL to verify connectivity.

Outbound Webhooks (Event Pushing)

Outbound webhooks push OpenClaw events to external systems.

Create an Outbound Webhook

openclaw webhooks create event-logger \
  --url "https://log.example.com/events" \
  --events message.received,message.sent,error \
  --secret "webhook-signing-secret"

Configure Event Types

Available event types:

message.received: User message received
message.sent: AI reply sent
message.error: Message processing error
channel.connected: Channel connected
channel.disconnected: Channel disconnected
agent.switched: Agent switched
system.started: Gateway started
system.stopped: Gateway stopped

openclaw webhooks update event-logger \
  --events message.received,message.sent,channel.disconnected

Outbound Webhook Payload Format

{
  "event": "message.received",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "channel": "telegram-main",
    "user": "user123",
    "message": "Hello",
    "sessionId": "session-456"
  },
  "signature": "sha256=abc123..."
}

Signature Verification

Outbound webhooks support HMAC-SHA256 signatures so receivers can verify the request origin:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Retry Policy

Retry configuration for outbound webhooks:

openclaw webhooks update event-logger \
  --retries 3 \
  --retry-delay 5000 \
  --timeout 10000

{
  "webhooks": {
    "outbound": {
      "event-logger": {
        "url": "https://log.example.com/events",
        "retries": 3,
        "retryDelay": 5000,
        "timeout": 10000,
        "retryStatusCodes": [500, 502, 503, 504]
      }
    }
  }
}

Webhook Logs

# View webhook call logs
openclaw webhooks logs event-logger --last 20

# View failed calls
openclaw webhooks logs event-logger --failed

Pause and Resume

openclaw webhooks pause event-logger
openclaw webhooks resume event-logger

Delete a Webhook

openclaw webhooks delete event-logger

Summary

The webhook system is the bridge between OpenClaw and the outside world. Inbound webhooks receive channel messages, and outbound webhooks push events to external systems. Properly configured retry policies and signature verification ensure reliable and secure message delivery.