Matrix Webhook
Post a message to a matrix room with a simple HTTP POST
Install
python3 -m pip install matrix-webhook
# OR
docker pull nim65s/matrix-webhook
Start
Create a matrix user for the bot, and launch this app with the following arguments and/or environment variables (environment variables update defaults, arguments take precedence):
matrix-webhook -h
# OR
python -m matrix_webhook -h
# OR
poetry run matrix-webhook -h
# OR
nix run github:nim65s/matrix-webhook -- -h
# OR
docker run --rm -it nim65s/matrix-webhook -h
usage: python -m matrix_webhook [-h] [-H HOST] [-P PORT] [-u MATRIX_URL] -i MATRIX_ID (-p MATRIX_PW | -t MATRIX_TOKEN) -k API_KEY [-v]
Configuration for Matrix Webhook.
options:
-h, --help show this help message and exit
-H HOST, --host HOST host to listen to. Default: `''`. Environment variable: `HOST`
-P PORT, --port PORT port to listed to. Default: 4785. Environment variable: `PORT`
-u MATRIX_URL, --matrix-url MATRIX_URL
matrix homeserver url. Default: `https://matrix.org`. Environment variable: `MATRIX_URL`
-i MATRIX_ID, --matrix-id MATRIX_ID
matrix user-id. Required. Environment variable: `MATRIX_ID`
-p MATRIX_PW, --matrix-pw MATRIX_PW
matrix password. Either this or token required. Environment variable: `MATRIX_PW`
-t MATRIX_TOKEN, --matrix-token MATRIX_TOKEN
matrix access token. Either this or password required. Environment variable: `MATRIX_TOKEN`
-k API_KEY, --api-key API_KEY
shared secret to use this service. Required. Environment variable: `API_KEY`
-v, --verbose increment verbosity level
Dev
poetry install
# or python3 -m pip install --user markdown matrix-nio
python3 -m matrix_webhook
Prod
A docker-compose.yml is provided:
- Use Traefik on the
webdocker network, eg. with proxyta.net - Put the configuration into a
.envfile - Configure your DNS for
${CHATONS_SERVICE:-matrixwebhook}.${CHATONS_DOMAIN:-localhost}
docker-compose up -d
Healthcheck
For load balancers which require a healthcheck endpoint to validate the availability of the service, the /health path can be used.
The endpoint will return a HTTP 200 status and a json document.
To the Healthcheck endpoint with Traefik and docker-compose, you can add:
services:
bot:
labels:
traefik.http.services.matrix-webhook.loadbalancer.healthcheck.path: /health
Test / Usage
curl -d '{"body":"new contrib from toto: [44](http://radio.localhost/map/#44)", "key": "secret"}' \
'http://matrixwebhook.localhost/!DPrUlnwOhBEfYwsDLh:matrix.org'
(or localhost:4785 without docker)
For Github
Add a JSON webhook with ?formatter=github, and put the API_KEY as secret
For Grafana
Add a webhook with an URL ending with ?formatter=grafana&key=API_KEY
For Gitlab
At the group level, Gitlab does not permit to setup webhooks. A workaround consists to use Google Chat or Microsoft Teams notification integration with a custom URL (Gitlab does not check if the url begins with the normal url of the service).
Google Chat
Add a Google Chat integration with an URL ending with ?formatter=gitlab_gchat&key=API_KEY
Microsoft Teams
Add a Microsoft Teams integration with an URL ending with ?formatter=gitlab_teams&key=API_KEY
Gitlab Webhook
At the project level, you can add a webhook with an URL ending with ?formatter=gitlab_webhook and put your API_KEY
as secret token. Not yet as pretty as other formatters, contributions welcome !
Github Release Notifier
To receiver notifications about new releases of projects hosted at github.com you can add a matrix webhook ending with ?formatter=grn&key=API_KEY to Github Release Notifier (grn).
Test room
#matrix-webhook:tetaneutral.net
Unit tests
docker-compose -f test.yml up --exit-code-from tests --force-recreate --build
Metadata
Release files for matrix-webhook 3.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| matrix_webhook-3.9.1.tar.gz | 9.9 kB | Without provenance | Details for matrix_webhook-3.9.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| matrix_webhook-3.9.1-py3-none-any.whl | Python 3 | none | any | Details for matrix_webhook-3.9.1-py3-none-any.whl |
Total release size: 20.3 kB
Release files / matrix_webhook-3.9.1.tar.gz
| Download URL | matrix_webhook-3.9.1.tar.gz |
|---|---|
| Size | 9.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0dca8382c9b66a5e0097d4d0675ac5801ac33c1b66e29c2932515d1ff6aff010
|
|
BLAKE2b-256 checksum How to use checksums |
e6054918e23756d502fff2d46871a2fa7339151be33dedb4445fe21aab35d999
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.2 CPython/3.10.12 Linux/6.5.0-1015-azure
|
Release files / matrix_webhook-3.9.1-py3-none-any.whl
| Download URL | matrix_webhook-3.9.1-py3-none-any.whl |
|---|---|
| Size | 10.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e8c7e573157360bee511ab08978e2a1e9a340c8a1d1691a70c01a8526df98505
|
|
BLAKE2b-256 checksum How to use checksums |
003a19d11321fba4244f899b4d8fcd1193292c8bde71c294d98a30d234ffe46b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.2 CPython/3.10.12 Linux/6.5.0-1015-azure
|
Security for matrix-webhook 3.9.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.