Flarum DingTalk Webhook Plugin

English | 中文

English

Push Flarum forum events to DingTalk group robots for real-time community notifications.

Features

• 🔔 Multiple Events: Support for discussions, posts, users, and groups events
• 📝 Markdown Format: Messages are formatted in DingTalk Markdown for clear presentation
• 🔐 Signature Security: Support for DingTalk robot signature verification
• 🏷️ Tag Filtering: Limit webhooks to trigger only for specific tags
• 👥 Group Permissions: Configure to push only content visible to specific user groups
• 🎨 Card-style Management: Intuitive card-based admin interface
• ✏️ Custom Templates: Support custom message templates for flexible formatting
• 🌐 Bilingual Support: Full English and Chinese interface

Installation

Install via Composer:

composer require jiushutech/flarum-dingtalk-webhook

DingTalk Robot Configuration

Step 1: Create DingTalk Group Robot

1. Open DingTalk and enter the group chat where you want to receive notifications
2. Click Group Settings (top right ...) → Smart Group Assistant → Add Robot
3. Select Custom robot
4. Set robot name (e.g., Forum Notifications) and avatar

Step 2: Configure Security Settings

DingTalk robots support three security settings. Signature mode is recommended:

Option 1: Signature (Recommended) ✅

1. Check Signature in security settings
2. System will generate a key starting with SEC, e.g., SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
3. Copy and save this key for later configuration in Flarum admin

Option 2: Custom Keywords

1. Check Custom Keywords
2. Set keywords (e.g., forum, notification)
3. Messages must contain at least one keyword to be sent successfully

Option 3: IP Address (Range)

1. Check IP Address (Range)
2. Enter your server's public IP address
3. Only requests from specified IPs will be accepted

Step 3: Get Webhook URL

1. After completing security settings, click Finish
2. System will display the Webhook URL in this format:

   https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   

3. Copy and save this URL

Step 4: Configure in Flarum Admin

1. Log in to Flarum admin panel
2. Find DingTalk Webhook extension in the left menu
3. Click Add Webhook button
4. Fill in configuration:

5. Click Save to complete configuration
6. Click Test Send to verify configuration

Supported Events

Custom Message Templates

Available Variables

Template Examples

Simple Notification Template

### {title}

**Author**: [{author}]({author_url})
**Time**: {timestamp}

{description}

[👉 View Details]({url})

Minimal Template

**{title}**

{description}

[View Details]({url}) | {author} | {timestamp}

Development

Frontend Build

cd js
npm install
npm run dev    # Development mode
npm run build  # Production build

License

MIT License

Author

JiushuTech

Links

• GitHub Repository
• Issue Tracker

中文

将 Flarum 论坛事件推送到钉钉群机器人，实现社区动态的实时通知。

功能特性

• 🔔 多事件支持：支持主题、回复、用户、用户组等多种事件类型
• 📝 Markdown 格式：推送消息采用钉钉 Markdown 格式，排版清晰
• 🔐 加签安全：支持钉钉机器人加签安全验证
• 🏷️ 标签过滤：可限制 Webhook 只在特定标签下触发
• 👥 组群权限：可配置只推送特定组群可见的内容
• 🎨 卡片式管理：后台采用卡片式界面，配置直观便捷
• ✏️ 自定义模板：支持自定义消息模板，灵活控制推送格式
• 🌐 双语支持：完整的中英文界面

安装

使用 Composer 安装：

composer require jiushutech/flarum-dingtalk-webhook

钉钉机器人配置

第一步：创建钉钉群机器人

1. 打开钉钉，进入需要接收通知的群聊
2. 点击群设置（右上角 ...）→ 智能群助手 → 添加机器人
3. 选择 自定义 机器人
4. 设置机器人名称（如：论坛通知）和头像

第二步：配置安全设置

钉钉机器人支持三种安全设置方式，推荐使用"加签"方式：

方式一：加签（推荐）✅

1. 在安全设置中勾选 加签
2. 系统会生成一个以 SEC 开头的密钥，如：SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
3. 复制并保存此密钥，稍后需要在 Flarum 后台配置

方式二：自定义关键词

1. 勾选 自定义关键词
2. 设置关键词（如：论坛、通知）
3. 发送的消息必须包含至少一个关键词才能发送成功

方式三：IP 地址（段）

1. 勾选 IP 地址（段）
2. 填写服务器的公网 IP 地址
3. 只有来自指定 IP 的请求才会被接受

第三步：获取 Webhook 地址

1. 完成安全设置后，点击 完成
2. 系统会显示 Webhook 地址，格式如下：

   https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   

3. 复制并保存此地址

第四步：在 Flarum 后台配置

1. 登录 Flarum 管理后台
2. 在左侧菜单找到 钉钉 Webhook 扩展
3. 点击 添加 Webhook 按钮
4. 填写配置信息：

5. 点击 保存 完成配置
6. 可点击 测试发送 验证配置是否正确

支持的事件

自定义消息模板

可用变量

模板示例

简洁通知模板

### {title}

**操作人**: [{author}]({author_url})
**时间**: {timestamp}

{description}

[👉 点击查看详情]({url})

极简模板

**{title}**

{description}

[查看详情]({url}) | {author} | {timestamp}

开发

前端构建

cd js
npm install
npm run dev    # 开发模式
npm run build  # 生产构建

常见问题

Q: 消息发送失败怎么办？

1. 检查 Webhook 地址是否正确
2. 如果使用加签，确认密钥是否正确
3. 如果使用关键词，确认消息内容包含关键词
4. 检查服务器是否能访问钉钉 API（oapi.dingtalk.com）

Q: 如何测试配置是否正确？

在 Webhook 卡片上点击"测试发送"按钮，会发送一条测试消息到钉钉群。

Q: 为什么某些事件没有触发？

1. 检查是否勾选了对应的事件类型
2. 检查标签过滤设置是否正确
3. 检查用户组权限设置

许可证

MIT License

作者

JiushuTech

链接

• GitHub 仓库
• 问题反馈