# 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:

NameDescriptionExecution timing
on_client_connackIssue connection acknowledgeWhen the server is ready to send connack packet
on_client_disconnecteddisconnectedWhen the client connection layer is about to close
on_message_publishmessage publishedBefore 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

KeyTypeDescription
actionstringEvent name
Value: "client_connack", cannot be modified
clientidstringClient's Client ID
usernamestringClient's Username, when there is no username, will use "undefined"
keepaliveintegerHeartbeat keepalive time applied by the client
proto_verintegerProtocol version number (3 | 4 | 5)
conn_ackstring"success" or failure

on_client_disconnected

KeyTypeDescription
actionstringEvent name
Value: "client_disconnected", cannot be modified
clientidstringClient's Client ID
usernamestringClient's Username, when there is no username, will use "undefined"
reasonstringError reasons

on_message_publish

KeyTypeDescription
actionstringEvent name
Value: "message_publish", cannot be modified
from_client_idstringPublisher's Client ID
from_usernamestringPublisher's Username, when there is no username, will use "undefined"
topicstringUnsubscribed topic
qosenumQoS level, and the optional value is 0 1 2
retainboolWhether it is a Retain message
payloadstringMessage Payload
tsintegerTimestamp (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
1

# 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>
1

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:

NameDescriptionExecution timing
client.connackIssue connection acknowledgeWhen the server is ready to send connack packet
client.disconnecteddisconnectedWhen the client connection layer is about to close
message.publishmessage publishedBefore 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

KeyTypeDescription
actionstringEvent name
Value: "client_connack", cannot be modified
clientidstringClient's Client ID
usernamestringClient's Username, when there is no username, will use "undefined"
keepaliveintegerHeartbeat keepalive time applied by the client
proto_verintegerProtocol version number (3 | 4 | 5)
conn_ackstring"success" or failure

client.disconnected

KeyTypeDescription
actionstringEvent name
Value: "client_disconnected", cannot be modified
clientidstringClient's Client ID
usernamestringClient's Username, when there is no username, will use "undefined"
reasonstringError reasons

message.publish

KeyTypeDescription
actionstringEvent name
Value: "message_publish", cannot be modified
from_client_idstringPublisher's Client ID
from_usernamestringPublisher's Username, when there is no username, will use "undefined"
topicstringUnsubscribed topic
qosenumQoS level, and the optional value is 0 1 2
retainboolWhether it is a Retain message
payloadstringMessage Payload
tsintegerTimestamp (second)