Integrate NodePing Alerts with Matrix

In this post, I will show you how you can get NodePing webhook alerts integrated with a Matrix server. In this demonstration, I will be focusing on the matrix-synapse server and Element client, namely, Element’s hosted web client for configuring Matrix to receive NodePing alerts. Matrix comes with some SDKs that can be used to more programmatically handle events and create bots, but I want to provide an option that doesn’t take much effort to set up.

To get started, I created a new account on my home server. This account will be the one that is receiving the webhooks and sending messages to the room. Think of it as a bot, and not a user to use on the daily. I followed the instructions from the synapse documentation to create a new user. For security purposes, I run a home server with registration disabled. I chose the alternate method of running `register_new_matrix_user` to create the new user, that way I did not have to enable registration on my server.

Now that I have the new user created, I signed into Element with the account I created and proceeded to create a private room.

I made the room invite only, and left end-to-end encryption enabled, though end-to-end encryption is optional. After the room is created, I invited the users to the group that I wanted to receive the alerts.

Creating the Webhook Contact

Now that I have my notifications user in place and users invited to the room, it is time to integrate Matrix with NodePing. I need 2 pieces of information:

1. The room ID
2. The “bot” user’s access token

Getting the Room ID

The Room ID is created when the room was created. I need to go to the settings menu for that room to get the ID. First, I click on the room’s 3-dot button so I can go to settings

Then, I go to Advanced to get the Internal room ID

Next, I need to get the Access Token for my user. This is a secret token you do not want to share with anyone. However, it will be used as part of my webhook contact. I went to the quick settings menu for my user that will be sending the NodePing alerts and selected “More options”:

I went to the Help & About menu and scrolled down to the bottom to get to the Access Token section. I copied the access token out. I also made note of the Homeserver mentioned below in the Advanced section. The Homeserver, Access Token, and Room ID are going to be needed in the next step to create the webhook.

Creating the Contact

Next, I signed into my NodePing account and selected Contacts, and Add new contact:

I gave my contact a name. Then I clicked the dropdown menu and selected Webhook. That shows another dropdown for Preset Services. I chose Matrix and clicked Apply Template. The default URL should be something like:

https://matrix.org/_matrix/client/r0/rooms/%5Byour encoded internal room id]/send/m.room.message

I am not using the default https://matrix.org home server, so I changed that. However, if you are using the default home server, keep matrix.org. Next I need to replace [your encoded internal room id] with the Room ID. The Room ID needs to be URI encoded. The “!” needs to be changed to “%21” and the “:” to “%3A”, like below

!abcde123456789:matrix.org

%21abcde123456789%3Amatrix.org

The final URL will look something like this:

https://matrix.org/_matrix/client/r0/rooms/%21abcde123456789%3Amatrix.org/send/m.room.message

Next I went to the Headers tab. There is a value with [YOUR AUTH HERE] in the Authorization header that needs to be replaced with the access token. I pasted in my access token. I kept the Body as the default. With the homeserver correctly set, the room ID in the POST URL, and the Authorization header set, I saved the check.

I created a check that I knew would fail intentionally and assigned the Matrix contact to the check and let it fail so I could get the alert and ensure it is working properly.

This confirms that the contact works, and now I can start assigning this contact method to my checks.

Some Useful Uses

Using with Notification Profiles

One thing I like to do is have two identical contact methods, but in one I add “IMPORTANT” to the body like below

{"body": "NodePing IMPORTANT: – {label}: {type} is {event}","msgtype": "m.text"}

This lets me do some tricks with notification schedules and notification sounds in Element. Maybe for some checks, I want to get notifications all the time, but I do not want the sound alert on my phone at certain times of the day. On my checks I have my Matrix contact that does not have “IMPORTANT” in the message send a notification all the time. However, the one that has “IMPORTANT” in the message will send on a certain schedule. In the Notifications settings on Element I created a keyword “IMPORTANT”, and then on the room I set notifications to only happen with Mentions & Keywords. That way, the messages sending all the time will not send an audible notification, but the messages with “IMPORTANT” will send me an audible notification.

Communicating About Incidents

With the Threads feature, when there is an incident, I can start a thread on that notification and communicate with the team about that incident, or I can make comments on the incident for future reference. This allows for convenient communication about an incident while not spamming the timeline where alerts are being displayed.

If you need help getting things working right, please let us know at support@nodeping.com.  If you don’t yet have a NodePing account, please sign up for our free 15-day trial.