Integrate Clawdbot AI assistant with external services using webhooks. Learn how to receive and send webhook events for automation.

Clawdbot Webhooks Overview

Clawdbot supports webhooks for integrating with external services. Webhooks enable event-driven automation, external triggers, and service-to-service communication.

Incoming Webhooks

Configuration

{
  "webhooks": {
    "incoming": {
      "enabled": true,
      "port": 3011,
      "secret": "your-webhook-secret"
    }
  }
}

Endpoint

POST http://localhost:3011/webhook/<hook-id>

Authentication

curl -X POST http://localhost:3011/webhook/my-hook \
  -H "X-Webhook-Secret: your-webhook-secret" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from external service"}'

Webhook Handlers

Define a Handler

{
  "webhooks": {
    "handlers": [
      {
        "id": "github-events",
        "path": "/github",
        "action": "run_agent",
        "agentId": "devops",
        "template": "New GitHub event: {{event.action}} on {{event.repository.name}}"
      }
    ]
  }
}

Handler Actions

Action	Description
`send_message`	Send message to channel
`run_agent`	Trigger agent with prompt
`forward`	Forward to another endpoint
`custom`	Custom handler function

Session Handling

Webhook Session Keys

Webhooks use dedicated sessions:

hook:<uuid>

Session Options

{
  "webhooks": {
    "handlers": [
      {
        "id": "alerts",
        "sessionMode": "persistent",
        "sessionKey": "alerts-session"
      }
    ]
  }
}

Outgoing Webhooks

Configuration

{
  "webhooks": {
    "outgoing": [
      {
        "id": "slack-notify",
        "url": "https://hooks.slack.com/services/xxx",
        "events": ["message_received", "agent_response"],
        "method": "POST"
      }
    ]
  }
}

Event Types

Event	Description
`message_received`	New message arrived
`agent_response`	Agent generated response
`session_started`	New session created
`session_ended`	Session expired/closed
`error`	Error occurred

Payload Format

Incoming Payload

{
  "event": "custom_event",
  "data": {
    "key": "value"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Outgoing Payload

{
  "type": "message_received",
  "session": "agent:main:whatsapp",
  "message": {
    "from": "+15551234567",
    "text": "Hello",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Security

Secret Verification

{
  "webhooks": {
    "incoming": {
      "secretHeader": "X-Webhook-Secret",
      "secret": "your-secret"
    }
  }
}

IP Allowlist

{
  "webhooks": {
    "incoming": {
      "allowedIPs": [
        "192.168.1.0/24",
        "10.0.0.1"
      ]
    }
  }
}

Error Handling

Retry Configuration

{
  "webhooks": {
    "outgoing": [
      {
        "id": "notify",
        "retry": {
          "maxAttempts": 3,
          "backoff": "exponential"
        }
      }
    ]
  }
}

Failure Handling

Failed webhooks logged
Retry with exponential backoff
Optional dead-letter queue

Examples

GitHub Integration

{
  "webhooks": {
    "handlers": [
      {
        "id": "github",
        "path": "/github",
        "action": "send_message",
        "target": {
          "channel": "discord",
          "peer": "dev-channel"
        },
        "template": "🔔 {{event.action}}: {{event.pull_request.title}}"
      }
    ]
  }
}

Alert Forwarding

{
  "webhooks": {
    "handlers": [
      {
        "id": "alerts",
        "path": "/alerts",
        "action": "run_agent",
        "agentId": "oncall",
        "template": "Alert: {{alert.name}} - {{alert.message}}"
      }
    ]
  }
}

Next Steps

Clawdbot Cron Jobs - Scheduled tasks
Clawdbot Gateway - Gateway configuration
Clawdbot Tools - Tool configuration

Clawdbot Webhooks

On this page