From 39f6ed2bd1197203093633c39cda1b1faa2615bd Mon Sep 17 00:00:00 2001 From: RockChinQ <1010553892@qq.com> Date: Thu, 4 Dec 2025 13:52:40 +0800 Subject: [PATCH] feat: add doc of webhook --- docs/.vitepress/config.mts | 2 + docs/en/tags/webhook.md | 104 +++++++++++++++++++++++++++++++++++++ docs/zh/tags/webhook.md | 104 +++++++++++++++++++++++++++++++++++++ 3 files changed, 210 insertions(+) create mode 100644 docs/en/tags/webhook.md create mode 100644 docs/zh/tags/webhook.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index a84b38937..5cde4447d 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -280,6 +280,7 @@ export default defineConfig({ text: "[Beta] Service API 参考", items: [ { text: "概述", link: "/zh/tags/readme" }, + { text: "Webhooks", link: "/zh/tags/webhook" }, ...sidebarZh.generateSidebarGroups({ linkPrefix: '/zh/tags/', }).map(group => ({ @@ -557,6 +558,7 @@ export default defineConfig({ text: "[Beta] Service API Reference", items: [ { text: "Overview", link: "/en/tags/readme" }, + { text: "Webhooks", link: "/en/tags/webhook" }, ...sidebarEn.generateSidebarGroups({ linkPrefix: '/en/tags/', }).map(group => ({ diff --git a/docs/en/tags/webhook.md b/docs/en/tags/webhook.md new file mode 100644 index 000000000..0fac455b6 --- /dev/null +++ b/docs/en/tags/webhook.md @@ -0,0 +1,104 @@ +# Webhooks + +Webhooks allow you to send bot message events to external services for processing. + +## Configure Webhooks + +1. In LangBot WebUI, click "API Integration" in the sidebar +2. Switch to the "Webhooks" tab +3. Click "+" to create a new webhook +4. Fill in: + - **Name**: Webhook identifier + - **URL**: Target URL to receive events + - **Description**: Optional + - **Status**: Enable or disable + +## Event Format + +### Person Message (bot.person_message) + +```json +{ + "uuid": "event-unique-id", + "event_type": "bot.person_message", + "data": { + "bot_uuid": "bot-uuid", + "adapter_name": "AdapterName", + "sender": { + "id": "user-id", + "name": "User Name" + }, + "message": [ + { + "type": "Plain", + "text": "Message content" + } + ], + "timestamp": 1234567890 + } +} +``` + +### Group Message (bot.group_message) + +```json +{ + "uuid": "event-unique-id", + "event_type": "bot.group_message", + "data": { + "bot_uuid": "bot-uuid", + "adapter_name": "AdapterName", + "group": { + "id": "group-id", + "name": "Group Name" + }, + "sender": { + "id": "user-id", + "name": "User Name" + }, + "message": [ + { + "type": "Plain", + "text": "Message content" + } + ], + "timestamp": 1234567890 + } +} +``` + +## Response Format + +Webhook services should return JSON: + +```json +{ + "status": "ok", + "skip_pipeline": false +} +``` + +### Parameters + +- **status**: Processing status (recommend "ok") +- **skip_pipeline**: Whether to skip LangBot pipeline processing + - `true`: Message won't continue in pipeline + - `false`: Message proceeds normally + +::: tip +`skip_pipeline` lets you completely take over message processing. When `true`, the message is only handled by your webhook service and won't trigger LangBot's AI features. +::: + +## Integration Example + +### Dify Workflow + +Use the [dify-plugin-langbot-trigger](https://github.com/langbot-app/dify-plugin-langbot-trigger) plugin to receive LangBot webhook events and create workflows in Dify. + +## Notes + +- Webhook URL must be accessible +- Request timeout: 15 seconds +- Failed requests don't affect normal processing +- Multiple webhooks execute in parallel +- Any webhook returning `skip_pipeline: true` skips pipeline processing diff --git a/docs/zh/tags/webhook.md b/docs/zh/tags/webhook.md new file mode 100644 index 000000000..6f7ce783e --- /dev/null +++ b/docs/zh/tags/webhook.md @@ -0,0 +1,104 @@ +# Webhooks + +Webhooks 允许您将机器人收到的消息事件发送到外部服务进行处理。 + +## 配置 Webhook + +1. 在 LangBot WebUI 中，点击侧边栏的 "API 集成" 按钮 +2. 切换到 "Webhooks" 标签页 +3. 点击 "+" 按钮创建新的 Webhook +4. 填写以下信息： + - **名称**：Webhook 的名称 + - **URL**：接收事件的目标 URL + - **描述**：可选说明 + - **状态**：启用或禁用 + +## 事件格式 + +### 个人消息 (bot.person_message) + +```json +{ + "uuid": "event-unique-id", + "event_type": "bot.person_message", + "data": { + "bot_uuid": "bot-uuid", + "adapter_name": "AdapterName", + "sender": { + "id": "user-id", + "name": "User Name" + }, + "message": [ + { + "type": "Plain", + "text": "消息内容" + } + ], + "timestamp": 1234567890 + } +} +``` + +### 群组消息 (bot.group_message) + +```json +{ + "uuid": "event-unique-id", + "event_type": "bot.group_message", + "data": { + "bot_uuid": "bot-uuid", + "adapter_name": "AdapterName", + "group": { + "id": "group-id", + "name": "Group Name" + }, + "sender": { + "id": "user-id", + "name": "User Name" + }, + "message": [ + { + "type": "Plain", + "text": "消息内容" + } + ], + "timestamp": 1234567890 + } +} +``` + +## 响应格式 + +Webhook 服务应返回 JSON 响应： + +```json +{ + "status": "ok", + "skip_pipeline": false +} +``` + +### 参数说明 + +- **status**: 处理状态（建议返回 "ok"） +- **skip_pipeline**: 是否跳过 LangBot 流水线处理 + - `true`: 消息不会继续在流水线中处理 + - `false`: 消息正常进入流水线处理 + +::: tip +`skip_pipeline` 允许您完全接管消息处理。设置为 `true` 时，消息只由 Webhook 服务处理，不触发 LangBot 的 AI 对话功能。 +::: + +## 集成示例 + +### Dify 工作流 + +使用 [dify-plugin-langbot-trigger](https://github.com/langbot-app/dify-plugin-langbot-trigger) 插件接收 LangBot webhook 事件，在 Dify 中创建工作流处理消息。 + +## 注意事项 + +- Webhook URL 必须可访问 +- 请求超时时间为 15 秒 +- 请求失败不影响消息正常处理 +- 支持配置多个 Webhook 并行执行 +- 任一 Webhook 返回 `skip_pipeline: true` 时跳过流水线处理