WebHook 集成教程

EMQX Edge 的 WebHook 功能支持 Broker 在发生特定 MQTT 事件时，自动向外部服务发送 HTTP POST 请求。这些事件包括客户端连接、消息发布、客户端断开连接等。通过该机制，你可以轻松将 EMQX Edge 与日志服务、分析平台或自定义 Dashboard 等外部系统集成，而无需编写自定义插件。

工作原理

当指定事件发生时，EMQX Edge 会组装包含结构化 JSON 数据的 HTTP POST 请求，并发送到用户定义的端点（url）。你可以在配置文件的 webhook 配置段下配置一条或多条事件规则。

启用并配置 WebHook 集成

你可以在 nanomq.conf 中添加以下配置片段来启用 WebHook 集成。更详细的配置项说明请参见 WebHook 配置。

webhook {
  url = "http://127.0.0.1:8888"                   # Destination endpoint for webhook requests
  headers.content-type = "application/json"       # Content-Type of the request
  body.encoding = plain                           # Payload encoding: plain, base64, or base62
  pool_size = 32                                  # Number of concurrent HTTP connections

  events = [
    {
      event = "on_message_publish"
      topic = "nmq/pub"
    }
    {
      event = "on_client_connack"
    }
    {
      event = "on_client_disconnected"
    }
  ]
}

关键参数：

• url：用于接收 WebHook 调用的 HTTP 端点。
• headers.content-type：Payload 的 Content-Type 请求头，推荐使用 JSON。
• body.encoding：Payload 编码方式，例如 plain 或 base64。
• pool_size：并发 HTTP worker 线程数。
• events：事件触发器列表；topic 过滤器可包含通配符，例如 nmq/#。

事件规则

Webhook 行为通过一组规则定义，每条规则监听一个特定事件，并可选监听某个主题。events 数组中的每一项定义一条 WebHook 规则。当事件发生时，EMQX Edge 会向预配置 URL 发送结构化 HTTP POST 请求。

事件规则字段

Field	Type	Description
event	string	触发 WebHook 的事件类型。支持值：on_message_publish、on_client_connack、on_client_disconnected。
topic	string	可选。用于限制触发范围的主题过滤器，仅适用于消息相关事件。

支持的事件

以下内置 MQTT 事件可触发 WebHook：

Event Name	Description	Trigger timing
on_client_connack	客户端连接确认	客户端完成 MQTT 连接握手，且 server 准备发送 CONNACT 报文时触发。
on_client_disconnected	客户端断开连接	客户端从 Broker 断开连接时触发。
on_message_publish	消息发布	消息发布到配置主题时触发。

HTTP 请求格式

事件触发后，EMQX Edge 会向配置的 url 发送 HTTP POST 请求。请求格式如下：

URL: <configured url>      # From the url field in the configuration file
Method: POST    # Fixed as POST method

Body: <JSON-formatted event data>    # Body is a JSON format string

不同事件的 body 可能不同。例如，on_client_connack 事件的 Payload 可能如下：

{"proto_ver":4,"keepalive":60,"conn_ack":"success","username":"wbhk_test","clientid":"wbhk_clientid","action":"client_connack"}

每种事件类型包含特定的 Payload Schema：

on_client_connack

Key	Type	Description
action	string	事件名称 值为 "client_connack"，不可修改
clientid	string	Client ID
username	string	客户端用户名；如果不存在则为 "undefined"
keepalive	integer	客户端使用的心跳 keepalive 时间
proto_ver	integer	MQTT 协议版本（3、4 或 5）
conn_ack	string	"success" 或失败原因

on_client_disconnected

Key	Type	Description
action	string	事件名称 值为 "client_disconnected"，不可修改
clientid	string	Client ID
username	string	客户端用户名；如果不存在则为 "undefined"
reason	string	错误原因

on_message_publish

Key	Type	Description
action	string	事件名称 值为 "message_publish"，不可修改
from_client_id	string	发布者 Client ID
from_username	string	发布者用户名；如果不存在则为 "undefined"
topic	string	主题名称
qos	enum	QoS 等级（0、1 或 2）
retain	bool	是否为 Retain 消息
payload	string	消息 Payload
ts	integer	时间戳，单位为秒

测试 WebHook 集成

本节演示如何验证 EMQX Edge 中 WebHook 事件是否正常触发。

启动 EMQX Edge 和测试 HTTP Server

测试时，你可以使用一个简单的 HTTP server 打印收到的请求，并返回 ok。

使用你的配置启动 EMQX Edge：

$ emqx-edge start --conf path/to/nanomq.conf

TIP

请确保你的 HTTP server 已启动，并监听配置中 webhook.url 字段指定的 URL。

触发 on_client_connack 事件

使用 MQTTX Client Tool 连接到 EMQX Edge。这会触发 on_client_connack 事件。

MQTTX 中的连接设置示例：

HTTP server 预期收到的请求：

header: content-type: [application/json]
Received: {"proto_ver":4,"keepalive":60,"conn_ack":"success","username":"wbhk_test","clientid":"wbhk_clientid","action":"client_connack"}

触发 on_message_publish 事件

接着，向主题 nmq/pub 发布一条消息：

预期 HTTP 请求：

header: content-type: [application/json]
Received: {"ts":1706703724960,"topic":"nmq/pub","retain":true,"qos":1,"action":"message_publish","from_username":"wbhk_test","from_client_id":"wbhk_clientid","payload":"Hello World!"}

TIP

Webhook 事件配置中的 topic 字段支持 MQTT 通配符。例如，设置 topic = "nmq/#" 将匹配 nmq/pub1、nmq/pub2 等所有子主题。

触发 on_client_disconnected 事件

断开客户端连接以触发 on_client_disconnected 事件。

预期 HTTP 请求：

header: content-type: [application/json]
Received: {"reason":"normal","username":"wbhk_test","clientid":"wbhk_clientid","action":"client_disconnected"}