# Configure with WebHook

NanoMQ is equipped with an event-driven WebHook interface, this section introduces how to enable the WebHook interface, relevant configuration items, and how WebHook is triggered by topics or events.

The webhook configuration file is located in etc/nanomq.conf, NanoMQ offers 2 formats of configuration files:

# Configure in HOCON

# Enable Webhook

webhook {
    ......
}

1
2
3

📢 Attention: for NanoMQ 0-14 ~ 0.18 users, you also need to activate this feature with the webhook.enable = true configuration item. For details, see Configuration v0.14

Starting from NanoMQ version 0.18, the enable option has been removed. Therefore, to enable the webhook configuration, simply add this module to the configuration file as shown above.

# Rule Syntax

NanoMQ provides the following configuration keys for WebHook:

event: string, taking a fixed value
topic: a string, functioning like a topic filter, the messaging forwarding action will only be triggered if the message topic matches the one specified in the rule.

Syntax

webhook.events = [
    ## Multi rules can be added here.
    {
        <Rule>
    }
]

1
2
3
4
5
6

Example

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

webhook.events = [
	{ 
		event = "on_message_publish"
		topic = "a/b/c"
	}
	{
		event = "on_message_publish"
		topic = "foo/#"
	}
]

1
2
3
4
5
6
7
8
9
10

# WebHook Trigger Events

WebHook can be triggered by the following events:

Name	Description	Execution timing
on_client_connack	Issue connection acknowledge	When the server is ready to send connack packet
on_client_disconnected	disconnected	When the client connection layer is about to close
on_message_publish	message published	Before the broker publishes (routes) the message

# Event Parameters

When an event occurs, the NanoMQ WebHook interface will package that event into an HTTP request. This request is then sent to a web server, the location of which is determined by a pre-configured URL.

The request format is:

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

Body: <JSON>    # Body is a JSON format string

1
2
3
4

The body for different events may differ. The following tables list the body parameters supported in each type of event:

on_client_connack

Key	Type	Description
action	string	Event name Value: "client_connack", cannot be modified
clientid	string	Client's Client ID
username	string	Client's Username, when there is no username, will use "undefined"
keepalive	integer	Heartbeat keepalive time applied by the client
proto_ver	integer	Protocol version number （3 ｜ 4 ｜ 5）
conn_ack	string	"success" or failure

on_client_disconnected

Key	Type	Description
action	string	Event name Value: "client_disconnected", cannot be modified
clientid	string	Client's Client ID
username	string	Client's Username, when there is no username, will use "undefined"
reason	string	Error reasons

on_message_publish

Key	Type	Description
action	string	Event name Value: "message_publish", cannot be modified
from_client_id	string	Publisher's Client ID
from_username	string	Publisher's Username, when there is no username, will use "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)

# Configure Multiple Rules

NanoMQ supports defining multiple trigger rules through the configuration file. This section will demonstrate by defining two WebHook trigger rules as an example:

Rule 1: When a message is sent to the "a/b/c" topic, trigger the WebHook.
Rule 2: When a client initiates a connection request, trigger the WebHook.

The sample configuration is as follows:

webhook.events = [
	url = "http://127.0.0.1:80"
	headers.content-type = "application/json"
	body.encoding = plain
	pool_size = 32

	{ 
		event = "on_message_publish"
		topic = "a/b/c"
	}
	{
		event = "on_client_connack"
	}
]

1
2
3
4
5
6
7
8
9
10
11
12
13
14

where,

event: WebHook triggered event, string, supported events include:

on_client_connack: Client connects
on_client_disconnected: Client disconnects
on_message_publish: Message published

topic: The topic that the message is published into, a string

# Configure in Key-Value Format

# Enable Webhook

web.hook.enable = true

# Rule Syntax

The trigger rule's value is a JSON string, and the available Keys are:

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

Syntax

web.hook.rule.<Event>.<Number>=<Rule>

Note: You can configure multiple trigger rules for one event, and use number to differentiate the rules.

Example

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

web.hook.rule.message.publish.1 = {"action": "on_message_publish", "topic": "a/b/c"}
web.hook.rule.message.publish.2 = {"action": "on_message_publish", "topic": "foo/#"}

1
2

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 fo/bar

# WebHook Trigger Events

The following events are currently supported:

Name	Description	Execution timing
client.connack	Issue connection acknowledge	When the server is ready to send connack packet
client.disconnected	disconnected	When the client connection layer is about to close
message.publish	message published	Before the server publishes (routes) the message

# Event Parameters

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

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

Body: <JSON>    # Body is a JSON format string

1
2
3
4

The body for different events may differ. The following tables list the body parameters supported in each type of event:

client.connack

Key	Type	Description
action	string	Event name Value: "client_connack", cannot be modified
clientid	string	Client's Client ID
username	string	Client's Username, when there is no username, will use "undefined"
keepalive	integer	Heartbeat keepalive time applied by the client
proto_ver	integer	Protocol version number （3 ｜ 4 ｜ 5）
conn_ack	string	"success" or failure

client.disconnected

Key	Type	Description
action	string	Event name Value: "client_disconnected", cannot be modified
clientid	string	Client's Client ID
username	string	Client's Username, when there is no username, will use "undefined"
reason	string	Error reasons

message.publish

Key	Type	Description
action	string	Event name Value: "message_publish", cannot be modified
from_client_id	string	Publisher's Client ID
from_username	string	Publisher's Username, when there is no username, will use "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)

← HTTP Configure with Configuration File →