Webhooks

Gateway có thể mở một HTTP webhook endpoint nhỏ để nhận trigger từ bên ngoài.

Bật Webhook

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

Lưu ý:

  • hooks.token là bắt buộc khi hooks.enabled=true.
  • hooks.path mặc định là /hooks.

Xác thực

Mỗi request phải có hook token. Nên dùng header:

  • Authorization: Bearer <token> (khuyên dùng)
  • x-openclaw-token: <token>
  • ?token=<token> (đã lỗi thời; sẽ hiện cảnh báo và bị xóa trong phiên bản major tương lai)

Endpoints

POST /hooks/wake

Payload:

{ "text": "System line", "mode": "now" }
  • text bắt buộc (string): Mô tả sự kiện (ví dụ: “New email received”).
  • mode tùy chọn (now | next-heartbeat): Có trigger Heartbeat ngay lập tức (mặc định now) hay đợi đến lần check định kỳ tiếp theo.

Hiệu ứng:

  • Đưa system event vào hàng đợi cho Session main
  • Nếu mode=now, trigger Heartbeat ngay lập tức

POST /hooks/agent

Payload:

{
  "message": "Run this",
  "name": "Email",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}
  • message bắt buộc (string): Prompt hoặc message để Agent xử lý.
  • name tùy chọn (string): Tên dễ đọc cho hook (ví dụ: “GitHub”), dùng làm prefix trong session summaries.
  • sessionKey tùy chọn (string): Key dùng để xác định Session của Agent. Mặc định là hook:<uuid> ngẫu nhiên. Dùng key cố định cho phép tạo cuộc hội thoại nhiều lượt trong context của hook.
  • wakeMode tùy chọn (now | next-heartbeat): Có trigger Heartbeat ngay lập tức (mặc định now) hay đợi đến lần check định kỳ tiếp theo.
  • deliver tùy chọn (boolean): Nếu true, phản hồi của Agent sẽ được gửi đến messaging channel. Mặc định là true. Các phản hồi chỉ là heartbeat acknowledgments sẽ tự động bị bỏ qua.
  • channel tùy chọn (string): Messaging channel để gửi. Một trong: last, whatsapp, telegram, discord, slack, mattermost (plugin), signal, imessage, msteams. Mặc định là last.
  • to tùy chọn (string): Định danh người nhận cho channel (ví dụ: số điện thoại cho WhatsApp/Signal, chat ID cho Telegram, channel ID cho Discord/Slack/Mattermost (plugin), conversation ID cho MS Teams). Mặc định là người nhận cuối cùng trong main session.
  • model tùy chọn (string): Override model (ví dụ: anthropic/claude-3-5-sonnet hoặc alias). Phải nằm trong danh sách model được phép nếu có giới hạn.
  • thinking tùy chọn (string): Override thinking level (ví dụ: low, medium, high).
  • timeoutSeconds tùy chọn (number): Thời gian tối đa cho Agent chạy, tính bằng giây.

Hiệu ứng:

  • Chạy một lượt Agent độc lập (có session key riêng)
  • Luôn đăng summary vào Session main
  • Nếu wakeMode=now, trigger Heartbeat ngay lập tức

POST /hooks/<name> (mapped)

Các tên hook tùy chỉnh được resolve qua hooks.mappings (xem phần cấu hình). Một mapping có thể biến payload tùy ý thành action wake hoặc agent, với template hoặc code transform tùy chọn.

Tóm tắt các tùy chọn mapping:

  • hooks.presets: ["gmail"] bật Gmail mapping có sẵn.
  • hooks.mappings cho phép các bạn định nghĩa match, action, và template trong config.
  • hooks.transformsDir + transform.module load một JS/TS module cho logic tùy chỉnh.
  • Dùng match.source để giữ một ingest endpoint chung (routing dựa trên payload).
  • TS transforms cần TS loader (ví dụ: bun hoặc tsx) hoặc file .js đã compile sẵn khi chạy.
  • Đặt deliver: true + channel/to trên mapping để route phản hồi đến chat surface (channel mặc định là last và fallback về WhatsApp).
  • allowUnsafeExternalContent: true tắt external content safety wrapper cho hook đó (nguy hiểm; chỉ dùng cho nguồn nội bộ đáng tin cậy).
  • openclaw webhooks gmail setup ghi config hooks.gmail cho openclaw webhooks gmail run. Xem Gmail Pub/Sub để biết flow Gmail watch đầy đủ.

Responses

  • 200 cho /hooks/wake
  • 202 cho /hooks/agent (async run đã bắt đầu)
  • 401 khi xác thực thất bại
  • 400 khi payload không hợp lệ
  • 413 khi payload quá lớn

Ví dụ

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'
curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

Dùng model khác

Thêm model vào agent payload (hoặc mapping) để override model cho lần chạy đó:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

Nếu các bạn bật agents.defaults.models, hãy đảm bảo model override nằm trong danh sách đó nhé.

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

Bảo mật

  • Giữ hook endpoints sau loopback, tailnet, hoặc reverse proxy đáng tin cậy.
  • Dùng hook token riêng; đừng dùng lại gateway auth token.
  • Tránh đưa raw payload nhạy cảm vào webhook logs.
  • Hook payload được coi là không đáng tin cậy và được bọc với safety boundaries theo mặc định. Nếu các bạn phải tắt điều này cho một hook cụ thể, đặt allowUnsafeExternalContent: true trong mapping của hook đó (nguy hiểm).