Zabbix Mattermost AlertScript

About

This is simply a Bash script that uses the custom alert script functionality within Zabbix along with the incoming web-hook feature of Mattermost.

Versions

This works with Zabbix 5.2.0

Huge thanks and appreciation to:

• Eric OC where this was originally forked from (https://github.com/ericoc/zabbix-slack-alertscript)
• Paul Reeves for the hint that Mattermost changed their API/URLs!
• Igor Shishkin for the ability to message users as well as channels!
• Hiromu Yakura for escaping quotation marks in the fields received from Zabbix to have valid JSON!

Installation

The script itself

This MattermostWebHooks.sh script needs to be placed in the AlertScriptsPath directory that is specified within the Zabbix servers' configuration file (zabbix_server.conf) and must be executable by the user running the zabbix_server binary (usually "zabbix") on the Zabbix server before restarting the Zabbix server software:

[root@zabbix ~]# grep AlertScriptsPath /etc/zabbix/zabbix_server.conf
### Option: AlertScriptsPath
AlertScriptsPath=/usr/lib/zabbix/alertscripts

[root@zabbix ~]# ls -lh /usr/lib/zabbix/alertscripts/MattermostWebHooks.sh
-rwxr-xr-x 1 root root 1.94K Nov 19 20:04 /usr/lib/zabbix/alertscripts/MattermostWebHooks.sh

If you do change AlertScriptsPath (or any other values) within zabbix_server.conf, a restart of the Zabbix server software is required.

Configuration

mattermost web-hook

An incoming web-hook integration must be created within your Mattermost account which can be done at :

https://<Your-Mattermost-Uri>/<Your-Team-Mattermost>/integrations/

Given the above screenshot, the incoming web-hook mattermost URL would be something like:

https://<your mattermost uri>/hooks/d9gezhz1sjbtmbzi7a5woaotcc

Make sure that you specify your correct Mattermost incoming web-hook URL and feel free to edit the sender user name at the top of the script:

# Mattermost incoming web-hook URL and user name
url='https://<your mattermost uri>/hooks/d9gezhz1sjbtmbzi7a5woaotcc'
username='zabbix'

Within the Zabbix web interface

When logged in to the Zabbix servers web interface with super-administrator privileges, navigate to the "Administration" tab, access the "Media Types" sub-tab, and click the "Create media type" button.

You need to create a media type as follows:

• Name: Mattermost-WebHook-Script
• Type: Script
• Script name: MattermostWebHooks.sh

Three minimum parameters must be indicated

• {ALERT.SENDTO}
• {ALERT.SUBJECT}
• {ALERT.MESSAGE}

...as shown here:

An optional fourth script parameter can be added to over-ride the url value that is hard-coded in the MattermostWebHooks.sh script. This makes it possible to re-use the script for multiple Mattermost teams.

An optional fifth script parameter can be added for proxy support. You can supply a host:port value (such as example.com:8080) that will be used when connecting to the Mattermost.com web-hook URL.

Finally, one or more template messages can then be created on the "Message Template" sub-tab.

Check that the "Subject" contains:

• Problem if you choose to send a "problem message"
• Resolved if you choose to send a "Resolved message"
• Updated if you choose to send an "Updated message"
• if none of the above is detected in this case the message will be considered as "Default message".

IMPORTANT: Make sure there is no newline in the message body. As that will break the JSON currently. Any line breaks should be replaced with \n as an example below :

Create User

Then, create a "Mattermost" user on the "Users" sub-tab of the "Administration" tab within the Zabbix servers web interface and specify this users "Media" as the "Mattermost" media type that was just created with the Mattermost channel ("#alerte-srv" in the example) or user name (such as "@alerte-srv") that you want messages to go to in the "Send to" field as seen below:

Testing

Assuming that you have set a valid Mattermost web-hook URL within your "MattermostWebHooks.sh" file, you can execute the script manually (as opposed to via Zabbix) from Bash on a terminal:

$ bash /usr/lib/zabbix/alertscripts/MattermostWebHooks.sh '#alerte-srv' "Problem test" "Oh no! c'est Something is wrong!"'

Alerting a specific user name results in the message actually coming from the "mattermostbot" user using a sort-of "spoofed" user name within the message. A channel alert is sent as you would normally expect from whatever user name you specify in "MattermostWebHooks.sh":

More Information

• Mattermost incoming web-hook functionality
• Zabbix 5.0 custom alertscripts documentation