[GH-ISSUE #175] Matrix integration

kerem commented

2026-02-25 23:41:15 +03:00

Owner

Originally created by @toXel on GitHub (Jun 3, 2018).
Original GitHub issue: https://github.com/healthchecks/healthchecks/issues/175

Sending notifications to a Matrix room would be really nice.

Originally created by @toXel on GitHub (Jun 3, 2018). Original GitHub issue: https://github.com/healthchecks/healthchecks/issues/175 Sending notifications to a [Matrix](https://matrix.org) room would be really nice.

kerem closed this issue

2026-02-25 23:41:15 +03:00

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@ParitoshBh commented on GitHub (Dec 16, 2018):

I am considering working on this. Just got the development setup up and running. It'd be great if someone can guide me as to how to go about adding a new integration!

@ParitoshBh commented on GitHub (Dec 16, 2018): I am considering working on this. Just got the development setup up and running. It'd be great if someone can guide me as to how to go about adding a new integration!

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@cuu508 commented on GitHub (Dec 18, 2018):

Hi @ParitoshBh, a good approach would be to pick one of the existing integrations, and use it as a blueprint for the new integration.

At a very high level, each integration has two parts: the UI for initial set up, and a class responsible for sending the actual notifications.

The initial setup consists of getting user's authorization / credentials. For email integration, it is a form asking the recipient's email address. For integrations that use Oauth2 for authorization, it is a form that kicks off the Oauth2 flow.

Each integration has it's own:

view function in hc/front/views.py
template in hc/templates/integrations/

The actual sending of notifications is relatively simple, in most cases it's just the matter of making a HTTP request with an appropriate payload. The notification sending code lives in hc/api/transports.py.

@cuu508 commented on GitHub (Dec 18, 2018): Hi @ParitoshBh, a good approach would be to pick one of the existing integrations, and use it as a blueprint for the new integration. At a very high level, each integration has two parts: the UI for initial set up, and a class responsible for sending the actual notifications. The **initial setup consists** of getting user's authorization / credentials. For email integration, it is a form asking the recipient's email address. For integrations that use Oauth2 for authorization, it is a form that kicks off the Oauth2 flow. Each integration has it's own: * view function in `hc/front/views.py` * template in `hc/templates/integrations/` The **actual sending of notifications** is relatively simple, in most cases it's just the matter of making a HTTP request with an appropriate payload. The notification sending code lives in `hc/api/transports.py`.

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@ParitoshBh commented on GitHub (Dec 19, 2018):

Appreciate the help, that got me started really quickly!

@ParitoshBh commented on GitHub (Dec 19, 2018): Appreciate the help, that got me started really quickly!

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@ParitoshBh commented on GitHub (Dec 27, 2018):

Here's what I have accomplished so far,

Generate access token, based on username/password provided (discarded later on)
Save access token, matrix server url, and group id (of group in which notification will be sent)

I am (sort of) stuck at understanding how notifications are dispatched. I can see the code in hc/api/transports.py but how its triggered is not clear.

P.S - Flow for slack will be very similar to one for Matrix however, to get started it needs client id, secret to work. Is there a test slack account available for testing?! Just trying to save some time.

@ParitoshBh commented on GitHub (Dec 27, 2018): Here's what I have accomplished so far, 1. Generate access token, based on username/password provided (discarded later on) 1. Save access token, matrix server url, and group id (of group in which notification will be sent) I am (sort of) stuck at understanding how notifications are dispatched. I can see the code in `hc/api/transports.py` but how its triggered is not clear. P.S - Flow for slack will be very similar to one for Matrix however, to get started it needs client id, secret to work. Is there a test slack account available for testing?! Just trying to save some time.

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@cuu508 commented on GitHub (Dec 27, 2018):

Good stuff!

The Transport subclass gets instantiated in hc.api.models.Channel.transport method.

Here's how the actual sending of notifications works:

manage.py sendalerts management command is running continuously and looking for any checks changing state
when it finds one, it looks up the Check instance and calls its send_alert() method
Check.send_alert loops through all assigned channels and calls notify() on each
Channel.notify instantiates the correct Transport subclass and calls its notify() method
The subclass then makes a HTTP request or sends an email

I'm not familiar with the Matrix protocol and am just starting to poke around it. What do you think about the following flow:

1. Initial Setup

Healthchecks server admin wants to enable Matrix integration on their Healthchecks server.

Healthchecks server admin sets up a bot account on their preferred Matrix server. For example, I, the admin of https://healthchecks.io, just set up an user account on matrix.org.

Healthchecks server admin puts the bot account credentials (server URL, username/password or access_token if it's long lived – not sure) in local_settings.py

2. Adding a Matrix Integration to a Healthchecks Account

A Healthchecks user wants to set up Matrix notification in their account.

They invite to their Matrix room. Next, they copy the room's identifier (the !xxxxx:server.tld thingy) and paste it in a "Integration Details" form in their Healthchecks account.

Upon receiving a room identifier, Healthchecks server accepts an invite, and stores the identifier.

3. Sending a Matrix Notification

Healthchecks server wants to send a notification to a configured Matrix room. It knows the room identifier, it has its access_key from local_settings.py, so sending the notification is one simple HTTP request.

Does this make sense? Can this work? If you know of other web apps that have integrated Matrix, what flow do they use?

My understanding is that, thanks to federation, it would be enough for the Healthchecks server admin to create a single bot account on one Matrix server.

@cuu508 commented on GitHub (Dec 27, 2018): Good stuff! The Transport subclass gets instantiated in `hc.api.models.Channel.transport` method. Here's how the actual sending of notifications works: * `manage.py sendalerts` management command is running continuously and looking for any checks changing state * when it finds one, it looks up the `Check` instance and calls its `send_alert()` method * `Check.send_alert` loops through all assigned channels and calls `notify()` on each * `Channel.notify` instantiates the correct Transport subclass and calls its `notify()` method * The subclass then makes a HTTP request or sends an email I'm not familiar with the Matrix protocol and am just starting to poke around it. What do you think about the following flow: **1. Initial Setup** Healthchecks server admin wants to enable Matrix integration on their Healthchecks server. Healthchecks server admin sets up a bot account on their preferred Matrix server. For example, I, the admin of https://healthchecks.io, just set up an user account on matrix.org. Healthchecks server admin puts the bot account credentials (server URL, username/password *or* access_token if it's long lived – not sure) in `local_settings.py` **2. Adding a Matrix Integration to a Healthchecks Account** A Healthchecks user wants to set up Matrix notification in their account. They invite <bot-email-address> to their Matrix room. Next, they copy the room's identifier (the !xxxxx:server.tld thingy) and paste it in a "Integration Details" form in their Healthchecks account. Upon receiving a room identifier, Healthchecks server accepts an invite, and stores the identifier. **3. Sending a Matrix Notification** Healthchecks server wants to send a notification to a configured Matrix room. It knows the room identifier, it has its access_key from local_settings.py, so sending the notification is one simple HTTP request. Does this make sense? Can this work? If you know of other web apps that have integrated Matrix, what flow do they use? My understanding is that, thanks to federation, it would be enough for the Healthchecks server admin to create a single bot account on one Matrix server.

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@ParitoshBh commented on GitHub (Dec 27, 2018):

That's more or less the flow I have in mind with some differing views,

Healthchecks server admin puts the bot account credentials (server URL, username/password or access_token if it's long lived – not sure) in local_settings.py

I can't really comment on whether they are long lived or not but based on the Specs (Refer 4.1.2.1), it looks like they do expire. However, that's a legacy spec reference and things might have changed.

They invite to their Matrix room.

Are you inclining towards creating Healthcheck bot on Matrix.org and then allowing users to add this bot to the room of their choice (on their server)? If that's the case, wouldn't there be additional maintenance?

Alternatively, I was thinking of offloading all of this to the user itself i.e.

Let the user create a new bot user on their instance (self-hosted or otherwise) say ServerBot and create a new room say ServerNotifications.
Make sure ServerBot is part of the ServerNotifications room.
On the integrations page, put in username/password of ServerBot (and server url) user following which an access_token will be retrieved and saved alongside server url, username. Password will be discarded once access_token is retrieved.
For notifications, saved access_token, url and username would suffice.

They invite to their Matrix room. Next, they copy the room's identifier (the !xxxxx:server.tld thingy) and paste it in a "Integration Details" form in their Healthchecks account.

Upon receiving a room identifier, Healthchecks server accepts an invite, and stores the identifier.

Didn't really think about doing it in this manner. I'll go back and see how api's for this work!

@ParitoshBh commented on GitHub (Dec 27, 2018): That's more or less the flow I have in mind with some differing views, > Healthchecks server admin puts the bot account credentials (server URL, username/password or access_token if it's long lived – not sure) in local_settings.py I can't really comment on whether they are long lived or not but based on the [Specs](https://matrix.org/docs/spec/legacy/) (Refer 4.1.2.1), it looks like they do expire. However, that's a _legacy_ spec reference and things might have changed. > They invite to their Matrix room. Are you inclining towards creating Healthcheck bot on Matrix.org and then allowing users to add this bot to the room of their choice (on their server)? If that's the case, wouldn't there be additional maintenance? Alternatively, I was thinking of offloading all of this to the user itself i.e. 1. Let the user create a new bot user on their instance (self-hosted or otherwise) say _ServerBot_ and create a new room say _ServerNotifications_. 1. Make sure _ServerBot_ is part of the _ServerNotifications_ room. 1. On the integrations page, put in username/password of _ServerBot_ (and server url) user following which an access_token will be retrieved and saved alongside server url, username. Password will be discarded once access_token is retrieved. 1. For notifications, saved access_token, url and username would suffice. > They invite to their Matrix room. Next, they copy the room's identifier (the !xxxxx:server.tld thingy) and paste it in a "Integration Details" form in their Healthchecks account. > Upon receiving a room identifier, Healthchecks server accepts an invite, and stores the identifier. Didn't really think about doing it in this manner. I'll go back and see how api's for this work!

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@cuu508 commented on GitHub (Dec 27, 2018):

Asking user to enter username, password, server URL and room ID would get the job done, but I'm wondering if it's possible to make the onboarding flow easier for the user: avoid manually creating bot account? Avoid looking up and copy-pasting the room id around?

Ideally it would be just:

Invite HealthchecksBot to a room
Do some action on Healthchecks
Done

Not sure how feasible that is.

Are you inclining towards creating Healthcheck bot on Matrix.org and then allowing users to add this bot to the room of their choice (on their server)? If that's the case, wouldn't there be additional maintenance?

The Telegram invitation works like that. User adds HealthchecksBot to a chat, and the bot responds with an invite link:

With Telegram, Healthchecks receives a webhook when the bot has new events. Not sure if that's possible with Matrix – I'd like to avoid having a long-running process that polls for new events.

Just found Application Service API and Push Gateway API but not sure how to use them.

@cuu508 commented on GitHub (Dec 27, 2018): Asking user to enter username, password, server URL and room ID would get the job done, but I'm wondering if it's possible to make the onboarding flow easier for the user: avoid manually creating bot account? Avoid looking up and copy-pasting the room id around? Ideally it would be just: 1. Invite HealthchecksBot to a room 2. Do some action on Healthchecks 3. Done Not sure how feasible that is. > Are you inclining towards creating Healthcheck bot on Matrix.org and then allowing users to add this bot to the room of their choice (on their server)? If that's the case, wouldn't there be additional maintenance? The Telegram invitation works like that. User adds HealthchecksBot to a chat, and the bot responds with an invite link: ![setup_telegram_2](https://user-images.githubusercontent.com/661859/50488013-2ac44500-0a09-11e9-9891-05f3b7e78a9d.png) With Telegram, Healthchecks receives a webhook when the bot has new events. Not sure if that's possible with Matrix – I'd like to avoid having a long-running process that polls for new events. Just found [Application Service API](https://matrix.org/docs/spec/application_service/r0.1.0.html) and [Push Gateway API](https://matrix.org/docs/spec/push_gateway/r0.1.0.html) but not sure how to use them.

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@ParitoshBh commented on GitHub (Dec 27, 2018):

With Telegram, Healthchecks receives a webhook when the bot has new events. Not sure if that's possible with Matrix – I'd like to avoid having a long-running process that polls for new events.

Webhooks aren't possible for now (https://github.com/matrix-org/matrix-appservice-bridge/issues/6). Based on this comment from one of the contributor, seems like using access_token for pushing messages to matrix server is the way to go instead of Application Service API or Push Gateway API.

I'd like to avoid having a long-running process that polls for new events.

I might be misinterpreting you completely (aggravated by lack of understanding of how healthchecks works), but if using Client Server API, healthchecks would be pushing a notification to matrix room in case of Up/Down event only.

@ParitoshBh commented on GitHub (Dec 27, 2018): > With Telegram, Healthchecks receives a webhook when the bot has new events. Not sure if that's possible with Matrix – I'd like to avoid having a long-running process that polls for new events. Webhooks aren't possible for now (https://github.com/matrix-org/matrix-appservice-bridge/issues/6). Based on [this comment](https://github.com/matrix-org/matrix-appservice-bridge/issues/6#issuecomment-236213711) from one of the contributor, seems like using access_token for pushing messages to matrix server is the way to go instead of Application Service API or Push Gateway API. > I'd like to avoid having a long-running process that polls for new events. I might be misinterpreting you completely (aggravated by lack of understanding of how healthchecks works), but if using Client Server API, healthchecks would be pushing a notification to matrix room in case of Up/Down event only.

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@cuu508 commented on GitHub (Dec 27, 2018):

You are correct – for sending notifications, if we have access key and a room id, then sending a notification is easy with the Client-Server API.

My previous comment was more about the onboarding aspect: getting the Healtchecks<->Matrix integration set up with the minimum number of steps and effort for the end user.

@cuu508 commented on GitHub (Dec 27, 2018): You are correct – for sending notifications, if we have access key and a room id, then sending a notification is easy with the Client-Server API. My previous comment was more about the onboarding aspect: getting the Healtchecks<->Matrix integration set up with the minimum number of steps and effort for the end user.

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@cuu508 commented on GitHub (Feb 22, 2019):

I'm looking at Matrix integration again – @ParitoshBh do you plan to continue work on this, or can I take over?

@cuu508 commented on GitHub (Feb 22, 2019): I'm looking at Matrix integration again – @ParitoshBh do you plan to continue work on this, or can I take over?

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@ParitoshBh commented on GitHub (Feb 22, 2019):

Sorry, I have been overly busy with personal commitments. Please go ahead and take over. I will be happy to test the integration though, if need be!

@ParitoshBh commented on GitHub (Feb 22, 2019): Sorry, I have been overly busy with personal commitments. Please go ahead and take over. I will be happy to test the integration though, if need be!

kerem commented

2026-02-25 23:41:16 +03:00

Author

Owner

@cuu508 commented on GitHub (Mar 11, 2019):

An initial version of the Matrix integration is ready, and deployed to https://healthchecks.io

I have a few concerns that might or might not be problems in practice:

Spam. Alice invites the Healthchecks bot into her room, #alices-room. Mallory knows about this, and knows #alices-room's alias or internal room ID. Mallory creates a bunch of checks with obnoxious names in their Healthchecks account, then adds a Matrix integration for #alices-room and starts sending messages.

Privacy concerns, rooms with sensitive info. When the Healthchecks bot is invited to a room, it has the ability to read room's messages. From a brief look, I didn't see a way to give it a write-only access (so it can only post messages, and cannot read other participants' messages). I, the operator of https://healthchecks.io, am not planning to log into the bot's account and read through the various rooms it is in. But nothing technically prevents me from doing that. It would be better if this was impossible.

Federation. The Healthchecks Matrix integration talks to a single pre-configured homeserver (matrix.org). It relies on federation to reach other homeservers. I don't know how universal or reliable the Matrix federation is. The current Healthchecks Matrix integration cannot reach isolated Matrix instances.

Server errors. When using the Matrix Client API, I've seen matrix.org sometimes return "Internal Server Error". In these cases, Healthchecks doesn't do any retries, it gives up.

@cuu508 commented on GitHub (Mar 11, 2019): An initial version of the Matrix integration is ready, and deployed to https://healthchecks.io I have a few concerns that might or might not be problems in practice: **Spam**. Alice invites the Healthchecks bot into her room, #alices-room. Mallory knows about this, and knows #alices-room's alias or internal room ID. Mallory creates a bunch of checks with obnoxious names in their Healthchecks account, then adds a Matrix integration for #alices-room and starts sending messages. **Privacy concerns, rooms with sensitive info**. When the Healthchecks bot is invited to a room, it has the ability to read room's messages. From a brief look, I didn't see a way to give it a write-only access (so it can only post messages, and cannot read other participants' messages). I, the operator of https://healthchecks.io, am not planning to log into the bot's account and read through the various rooms it is in. But nothing technically prevents me from doing that. It would be better if this was impossible. **Federation**. The Healthchecks Matrix integration talks to a single pre-configured homeserver (matrix.org). It relies on federation to reach other homeservers. I don't know how universal or reliable the Matrix federation is. The current Healthchecks Matrix integration cannot reach isolated Matrix instances. **Server errors**. When using the Matrix Client API, I've seen matrix.org sometimes return "Internal Server Error". In these cases, Healthchecks doesn't do any retries, it gives up.

Rows
Columns

[GH-ISSUE #175] Matrix integration #121