turt2live/matrix-appservice-webhooks

matrix-appservice-webhooks

注意：推荐使用 https://github.com/Half-Shot/matrix-hookshot 作为此旧版桥接工具的替代方案 :)

![TravisCI 徽章]([***]

Matrix的Slack兼容Webhook。在Matrix上讨论：#webhooks:t2bot.io

镜像概述和主要用途

matrix-appservice-webhooks是一个Matrix应用服务，提供与Slack兼容的Webhook功能，允许外部服务通过HTTP请求向Matrix房间发送消息。用户可在Matrix房间中配置Webhook，接收来自第三方服务的通知或消息，并支持自定义消息格式、发送者显示名称和头像。

核心功能和特性

• Slack兼容：支持Slack风格的Webhook消息格式
• 消息格式：支持纯文本（plain）和HTML格式
• 自定义发送者：可设置显示名称（displayName）和头像（avatarUrl）
• 表情转换：自动将:emoji:格式转换为对应表情符号（可禁用）
• 消息类型：支持普通消息、通知（notice）和表情动作（emote）

使用场景和适用范围

• 第三方服务向Matrix房间发送通知（如CI/CD构建结果、系统告警）
• 自动化工具通过Webhook与Matrix房间交互
• 需要将外部系统消息集成到Matrix聊天环境的场景

使用方法和配置说明

基本使用

1. 邀请Webhook桥接机器人到房间：@_webhook:t2bot.io
2. 在房间中发送消息 !webhook
3. 桥接机器人将在私信中发送Webhook链接（需具有房间配置权限）

发送消息的JSON请求体

json
{
  "text": "Hello world!",
  "format": "plain",
  "displayName": "My Cool Webhook",
  "avatarUrl": "http://i.imgur.com/IDOBtEJ.png"
}

参数说明：

• text：消息内容（必填）
• format：消息格式，可选值：plain（纯文本）或html（HTML）
• displayName：发送者显示名称
• avatarUrl：发送者头像URL
• emoji：是否自动转换表情符号，默认为true，设为false禁用转换
• msgtype：消息类型，可选值：notice（通知）或emote（表情动作）

安装要求

• Matrix家庭服务器（如Synapse）
• Node.js 9或更高版本

手动安装步骤

1. 克隆仓库并安装依赖

   bash
   git clone http://github.com/turt2live/matrix-appservice-webhooks
   cd matrix-appservice-webhooks
   npm install
   

2. 复制示例配置文件并修改

   bash
   cp config/sample.yaml config/config.yaml
   

   编辑config/config.yaml填写必要配置项

3. 生成应用服务注册文件

   bash
   node index.js -r -u "http://localhost:9000" -c config/config.yaml
   

   注意：默认运行URL为http://localhost:9000，如有其他应用服务或特殊需求，需修改主机名和端口

4. 将注册文件链接到Synapse目录

   bash
   cd ~/.synapse
   ln -s ../matrix-appservice-webhooks/appservice-registration-webhooks.yaml appservice-registration-webhooks.yaml
   

5. 在homeserver.yaml中添加注册文件

   yaml
   ...
   app_service_config_files: ["appservice-registration-webhooks.yaml"]
   ...
   

6. 重启Synapse服务

   bash
   synctl restart
   

运行服务

使用安装时指定的端口（默认9000），从仓库目录执行：

bash
node index.js -p 9000 -c config/config.yaml -f appservice-registration-webhooks.yaml

服务将在启动后不久开始工作。

Docker部署

镜像获取

可自行构建镜像：

bash
docker build -t matrix-appservice-webhooks .

或使用docker.io上的官方镜像：

bash
docker run -p 9000:9000 -v /path/to/webhooks/dir:/data turt2live/matrix-appservice-webhooks

数据目录说明

/path/to/webhooks/dir需包含以下文件：

• appservice-registration-webhooks.yaml：应用服务注册文件
• config.yaml：桥接配置文件
• database.json：数据库文件

其他桥接相关数据也将存储在此目录。

示例注册文件 appservice-registration-webhooks.yaml

yaml
id: webhooks
hs_token: A_RANDOM_ALPHANUMERIC_STRING  # 请修改此值
as_token: ANOTHER_RANDOM_ALPHANUMERIC_STRING  # 请修改此值
namespaces:
  users:
    - exclusive: true
      regex: '@_webhook.*'
  aliases: []
  rooms: []
url: 'http://localhost:9002'  # 可能需要修改（应指向桥接服务）
sender_localpart: _webhook
rate_limited: false
protocols: null