# 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 {
......
}
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 valuetopic
: 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>
}
]
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/#"
}
]
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
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"
}
]
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 connectson_client_disconnected
: Client disconnectson_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/#"}
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
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) |