Webhook Configuration

OpenClaw automatically configures webhooks for your Telegram bot. This guide explains how webhooks work and how to manage them.

What is a Webhook?

A webhook is an HTTPS endpoint that receives real-time updates from Telegram when users interact with your bot. Instead of polling for updates, Telegram pushes messages directly to your server.

Webhook vs Polling

Webhook (OpenClaw Default)

Instant message delivery
Lower latency (typically 50-200ms)
More efficient resource usage
Requires HTTPS endpoint

Polling (Not Used)

Periodic checking for updates
Higher latency (1-5 seconds typical)
Increased API calls
Works without public endpoint

Automatic Webhook Configuration

When you connect a bot to OpenClaw, we automatically:

Generate unique webhook URL for your bot
Register URL with Telegram Bot API
Configure SSL/TLS certificates
Set up request validation and signing
Enable automatic retry on failures

No manual webhook configuration required. Everything is handled automatically.

Webhook URL Structure

Your bot's webhook URL follows this pattern:

https://webhooks.openclaw.ai/bot/{bot_id}/{secret_token}

bot_id - Your bot's unique identifier
secret_token - Security token for request validation

Never share your webhook URL. It contains sensitive authentication information.

Webhook Security

Request Validation

OpenClaw validates every incoming webhook request:

HTTPS Only - All requests must use TLS 1.2+
IP Whitelist - Only Telegram server IPs accepted
Secret Token - Validates request authenticity
Payload Signature - Cryptographic verification of message integrity

SSL/TLS Configuration

Automatic certificate management
TLS 1.3 preferred, TLS 1.2 minimum
Perfect Forward Secrecy (PFS) enabled
Modern cipher suites only

Managing Webhooks

View Webhook Status

In the Portal:

Navigate to "Bots" → Select your bot
View "Webhook" section
Check status indicators:
- Active - Receiving messages normally
- Pending - Configuration in progress
- Failed - Connection issue detected

Webhook Health Monitoring

OpenClaw continuously monitors webhook health:

Last Message Received - Timestamp of most recent update
Success Rate - Percentage of successful deliveries (last 24h)
Average Latency - Message delivery time
Error Count - Failed deliveries requiring retry

Webhook Logs

Access detailed webhook logs in Portal:

Incoming message payload
Processing duration
Response sent to Telegram
Error messages and stack traces

Troubleshooting

Webhook Not Receiving Messages

Check Bot Status

Verify bot shows "Active" in Portal
Confirm subscription is current
Check for service notifications

Test Bot Directly

Send message to bot in Telegram
Check Portal logs for incoming webhook
Verify response sent back to user

Verify Telegram Settings

Ensure bot not blocked by user
Check bot has necessary permissions in groups
Confirm webhook not overridden elsewhere

High Latency or Timeouts

Causes:

Network congestion
Skill processing taking too long
External API dependencies slow

Solutions:

Review skill configuration
Optimize response generation
Check third-party service status
Contact support for infrastructure issues

Duplicate Messages

If your bot processes messages twice:

Likely Causes:

Multiple webhook endpoints configured
Bot token used in multiple services
Race condition in message handling

Resolution:

Verify only OpenClaw webhook registered
Check bot not connected elsewhere
Review BotFather webhook info (/setwebhook)

Webhook Best Practices

Response Time

Telegram expects webhook responses within 60 seconds:

Acknowledge receipt quickly
Process async for long operations
Use background jobs for heavy tasks

Error Handling

Return HTTP 200 even for processing errors
Log errors for debugging
Implement graceful degradation

Rate Limiting

Telegram limits bot API calls:

30 messages per second
20 messages per minute per chat
OpenClaw handles rate limiting automatically

Advanced Configuration

Custom Webhook Headers (Ultra Tier)

Add custom headers to webhook requests:

{
  "webhook_headers": {
    "X-Custom-Auth": "your-api-key",
    "X-Environment": "production"
  }
}

Webhook Forwarding (Ultra Tier)

Forward webhook events to external endpoints:

{
  "forward_to": "https://your-api.com/telegram-webhook",
  "forward_method": "POST",
  "forward_headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}

Webhook Setup