Mattermost integrations: Sending alerts to a channel with an incoming webhook
Incoming webhooks are the easiest way to let other programs send messages to Mattermost
(Originally published at controlaltdieliet.be)
Last week, we shared an introduction on how to use incoming webhooks to integrate with Mattermost. Here’s an example of how to use them in action.
Monitoring refrigerator temperatures
Our fridges need to retain a constant temperature. When the temperature gets too high, we have to react quickly to prevent food from spoiling. If the temperature increases, it could be a sign that there’s a problem with the fridge or that someone didn’t close it well.
We built a monitoring system that warned relevant people by email when the fridge got too hot. But let’s be honest: Email will become like faxes—once great but soon outdated.
We integrated the monitoring system with Mattermost because it enables us to use push notifications to see at glance if anyone checked the situation. We have an overview in the channel that outlines how often incidents occur.
Keep reading to learn how you can build an incoming webhook for a similar use case.
Create the incoming webhook in four steps
1. Go to the Menu and choose Integrations:
2. On the following screen, choose Incoming Webhooks:
3. On the next screen, you can see your existing incoming webhooks and add a new one.
4. Now, you can set up the incoming webhook in five simple steps:
- Give the incoming webhook a title
- Give the incoming webhook a description
- Select the default channel that receives the messages that the incoming webhook is sending
- Choose if you want to lock the incoming webhook to the channel or that it is allowed to send to other channels as well
- Click the save button
See, that wasn’t that hard. You get a confirmation with a very important URL, which listens to the messages we will be sending.
Write some code
Ok, you are all set! Let’s start sending messages!
Do you want to do a quick check if it’s working? You can check it with curl:
curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, this is some text\nThis is more text. :tada:"}' https://{your-mattermost-site}/hooks/xxx-generatedkey-xxx
# or
curl -i -X POST --data-urlencode 'payload={"text": "Hello, this is some text\nThis is more text. :tada:"}' https://{your-mattermost-site}/hooks/xxx-generatedkey-xxx
#for windows make sure that the double quotes are escaped with a backslash!
curl -i -X POST -H "Content-Type: application/json" -d "{\"text\":Hello, this is some text\nThis is more text. :tada:\"}" https://{your-mattermost-site}/hooks/xxx-generatedkey-xxxOr with Python:
import requests
# the part where we read the actual temperatures is replaced by the next line
temperature= 3.14159265358979323846
#actual code for sending
headers = {'Content-Type': 'application/json',}
values = '{ "text": "The temperature of the fridge is now '+str(temperature).replace(".",",")+' degrees Celcius"}'
response = requests.post('https://{your-mattermost-site}/hooks/xxx-generatedkey-xxx', headers=headers, data=values) If you don’t like JSON, you can send a plain webrequest as well:
import requests
# the part where we read the actual temperatures is replaced by the next line
temperature= 3.14159265358979323846
#actual code for sending
headers = {}
values = '{"text": "The temperature of the fridge is now '+str(temperature).replace(".",",")+' degrees Celcius"}'
response = requests.post('https://{your-mattermost-site}/hooks/xxx-generatedkey-xxx,headers=headers data=values)
Or if you prefer NodeJS:
const https = require('https')
temperature= 3.14159265358979323846
const data = JSON.stringify({
text: "The temperature of the fridge is now "+temperature+" degrees Celcius"
})
const options = {
hostname: '{your-mattermost-site}',
port: 443,
path: '/hooks/{xxx-generatedkey-xxx}',
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Content-Length': data.length
}
}
const req = https.request(options, res => {
console.log(`statusCode: ${res.statusCode}`)
res.on('data', d => {
process.stdout.write(d)
})
})
req.write(data)
req.end()More options
Sending to other channels
If you didn’t check the Lock to this channel checkbox, you can send messages to other channels by sending a channel-variable:
values = '{ "channel": "the-icrowd","text": "The temperature of the fridge is now 42 degrees Celcius"}'Changing the username
If you want to use another username to appear as the sender, you can add the username variable. This setting is default disabled and must be enabled in the Management Console.
values = '{"username":"The Coolest Fridge","text": "The temperature of the fridge is now -42 degrees Celcius"}'Changing the profile picture
If you want to change the profile picture, add the icon_url in the request.
values = '{"icon_url":"https://emojipedia-us.s3.dualstack.us-west-1.amazonaws.com/thumbs/120/apple/198/freezing-face_1f976.png","text": "The Fonz says the fridge is cool enough"}'Adding emoticons
If you want to add an emoticon in the text, add a shortcode like :tada: in the text.
values = '{"text": ""Wow, this works :tada:}'Adding more layout
If you are not familiar with Markdown layout, you can find an introduction in the Mattermost Documentation.
values = '{"text": "| Left-Aligned | Center Aligned | Right Aligned |
| :------------ |:---------------:| -----:|
| Left column 1 | this text | $100 |
| Left column 2 | is | $10 |
| Left column 3 | centered | $1 |"}'Debugging
Is something not working as expected? Go to the System Console and click on Logging under Environment.
In the Logging section, enable Webhook Debugging and set File Log Level to Debug.
You’ll find all the relevant information you need in the logfiles (or in the console if you enabled logging to the console).
My most common mistake is a typo in the request. It gives me an “Unable to parse incoming data” error.
More information
For more comprehensive information on incoming webhooks, check out the official Mattermost documentation. You can also always ask for help over on the Mattermost Forum.
