WebHook

The internal implementation of WebHook is based on hooks, but it is closer to the top level. It obtains various events in EMQX Broker through the callback function mounted on the hook, and forwards them to the web server configured in emqx_web_hook.

Taking the client.connected event as an example, the event delivery process is as follows:

TIP

WebHook processes events in one-way pattern. It only supports pushing events in EMQX Broker to Web services, and does not care about the return of Web services. With the help of Webhooks, many services such as device going online, online and offline recording, subscription and message storage, and message delivery confirmation can be completed.

The webhook configuration file is located in: , the detailed description of configuration items can be found in Configuration Item.

Trigger rules can be configured in etc/plugins/emqx_web_hook.conf. The configuration format is as follows:

The following events are currently supported:

Multiple trigger rules can be configured for the same event, and events with the same configuration should be incremented in sequence.

action: string, taking a fixed value
topic: a string, indicating a topic filter, the operation topic can only trigger the forwarding of the event if it matches the topic

For example, we only forward messages matching the topics of a/b/c and foo/# to the web server, and the configuration should be:

In this way, Webhook will only forward messages matching the topics of a/b/c and foo/#, such as foo/bar, etc., instead of forwarding a/b/d or .

When the event is triggered, Webhook will group each event into an HTTP request and sent it to the web server configured by url according to the configuration. The request format is:

For different events, the content of the request body is different. The following table lists the parameters of the body in each event:

client.connect

Key	Type	Description
action	string	event name fixed at：”client_connect”
clientid	string	client ClientId
username	string	client Username, When not existed, the value is “undefined”
ipaddress	string	client source IP address
keepalive	integer	Heartbeat keepalive time applied by client
proto_ver	integer	Protocol version number

client.connack

Key	Type	Description
action	string	event name fixed at: “client_connack”
clientid	string	client ClientId
username	string	client Username, When not existed, the value is “undefined”
ipaddress	string	client source IP address
keepalive	integer	Heartbeat keepalive time applied by client
proto_ver	integer	Protocol version number
conn_ack	string	“success” means success, other means failure

client.connected

client.disconnected

Key	Type	Description
action	string	event name fixed at: “client_disconnected”
clientid	string	client ClientId
username	string	client Username, When not existed, the value is “undefined”
reason	string	error reason

Key	Type	Description
action	string	event name fixed at: “client_subscribe”
clientid	string	Client ClientId
username	string	Client Username, When not existed, the value is “undefined”
topic	string	Topics to be subscribed
opts	json	Subscription parameters

opts includes

client.unsubscribe

Key	Type	Description
action	string	event name fixed at:”client_unsubscribe”
clientid	string	client ClientId
username	string	client Username, When not existed, the value is “undefined”
topic	string	unsubscribed topic

session.subscribed: same as client.subscribe，action is session_subscribed

session.unsubscribed: same as client.unsubscribe，action is session_unsubscribe

session.terminated: same as client.disconnected，action is

message.publish

Key	Type	Description
action	string	event name fixed at: “message_publish”
from_client_id	string	Publisher’s ClientId
from_username	string	Publisher’s Username, When not existed, the value is “undefined”
topic	string	Unsubscribed topic
qos	enum	QoS level, and the optional value is `0` `1` `2`
retain	bool	Whether it is a Retain message
payload	string	Message Payload
ts	integer	Timestamp (second)

message.delivered

message.acked

Key	Type	Description
action	string	event name fixed at: “message_acked”
clientid	string	Receiver’s ClientId
from_client_id	string	Publisher’s ClientId
from_username	string	Publisher’s Username, When not existed, the value is “undefined”
topic	string	Unsubscribed topic
qos	enum	QoS level, and the optional value is `0` `1`
retain	bool	Whether it is a Retain message
payload	string	Message Payload
ts	integer	Timestamp (second)