# Matrix Webhook
[](https://github.com/nim65s/matrix-webhook/actions/workflows/test.yml)
[](https://github.com/nim65s/matrix-webhook/actions/workflows/lint.yml)
[](https://hub.docker.com/r/nim65s/matrix-webhook)
[](https://pypi.org/project/matrix-webhook/)
[](https://results.pre-commit.ci/latest/github/nim65s/matrix-webhook/main)
[](https://github.com/psf/black)
[](https://github.com/charliermarsh/ruff)
[](https://codecov.io/gh/nim65s/matrix-webhook)
[](https://codeclimate.com/github/nim65s/matrix-webhook/maintainability)
[](https://badge.fury.io/py/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](https://traefik.io/) on the `web` docker network, eg. with
[proxyta.net](https://framagit.org/oxyta.net/proxyta.net)
- Put the configuration into a `.env` file
- 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:
```yaml
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)](https://github.com/femtopixel/github-release-notifier).
## Test room
[#matrix-webhook:tetaneutral.net](https://matrix.to/#/!DPrUlnwOhBEfYwsDLh:matrix.org)
## Unit tests
```
docker-compose -f test.yml up --exit-code-from tests --force-recreate --build
```
Raw data
{
"_id": null,
"home_page": "https://github.com/nim65s/matrix-webhook",
"name": "matrix-webhook",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Guilhem Saurel",
"author_email": "guilhem.saurel@laas.fr",
"download_url": "https://files.pythonhosted.org/packages/e6/05/4918e23756d502fff2d46871a2fa7339151be33dedb4445fe21aab35d999/matrix_webhook-3.9.1.tar.gz",
"platform": null,
"description": "# Matrix Webhook\n\n[](https://github.com/nim65s/matrix-webhook/actions/workflows/test.yml)\n[](https://github.com/nim65s/matrix-webhook/actions/workflows/lint.yml)\n[](https://hub.docker.com/r/nim65s/matrix-webhook)\n[](https://pypi.org/project/matrix-webhook/)\n[](https://results.pre-commit.ci/latest/github/nim65s/matrix-webhook/main)\n\n[](https://github.com/psf/black)\n[](https://github.com/charliermarsh/ruff)\n[](https://codecov.io/gh/nim65s/matrix-webhook)\n[](https://codeclimate.com/github/nim65s/matrix-webhook/maintainability)\n[](https://badge.fury.io/py/matrix-webhook)\n\nPost a message to a matrix room with a simple HTTP POST\n\n## Install\n\n```\npython3 -m pip install matrix-webhook\n# OR\ndocker pull nim65s/matrix-webhook\n```\n\n## Start\n\nCreate a matrix user for the bot, and launch this app with the following arguments and/or environment variables\n(environment variables update defaults, arguments take precedence):\n\n```\nmatrix-webhook -h\n# OR\npython -m matrix_webhook -h\n# OR\npoetry run matrix-webhook -h\n# OR\nnix run github:nim65s/matrix-webhook -- -h\n# OR\ndocker run --rm -it nim65s/matrix-webhook -h\n```\n\n```\nusage: 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]\n\nConfiguration for Matrix Webhook.\n\noptions:\n -h, --help show this help message and exit\n -H HOST, --host HOST host to listen to. Default: `''`. Environment variable: `HOST`\n -P PORT, --port PORT port to listed to. Default: 4785. Environment variable: `PORT`\n -u MATRIX_URL, --matrix-url MATRIX_URL\n matrix homeserver url. Default: `https://matrix.org`. Environment variable: `MATRIX_URL`\n -i MATRIX_ID, --matrix-id MATRIX_ID\n matrix user-id. Required. Environment variable: `MATRIX_ID`\n -p MATRIX_PW, --matrix-pw MATRIX_PW\n matrix password. Either this or token required. Environment variable: `MATRIX_PW`\n -t MATRIX_TOKEN, --matrix-token MATRIX_TOKEN\n matrix access token. Either this or password required. Environment variable: `MATRIX_TOKEN`\n -k API_KEY, --api-key API_KEY\n shared secret to use this service. Required. Environment variable: `API_KEY`\n -v, --verbose increment verbosity level\n```\n\n## Dev\n\n```\npoetry install\n# or python3 -m pip install --user markdown matrix-nio\npython3 -m matrix_webhook\n```\n\n## Prod\n\nA `docker-compose.yml` is provided:\n\n- Use [Traefik](https://traefik.io/) on the `web` docker network, eg. with\n [proxyta.net](https://framagit.org/oxyta.net/proxyta.net)\n- Put the configuration into a `.env` file\n- Configure your DNS for `${CHATONS_SERVICE:-matrixwebhook}.${CHATONS_DOMAIN:-localhost}`\n\n```\ndocker-compose up -d\n```\n\n### Healthcheck\n\nFor load balancers which require a healthcheck endpoint to validate the availability of the service, the `/health` path can be used.\nThe endpoint will return a **HTTP 200** status and a json document.\n\nTo the Healthcheck endpoint with Traefik and docker-compose, you can add:\n\n```yaml\nservices:\n bot:\n labels:\n traefik.http.services.matrix-webhook.loadbalancer.healthcheck.path: /health\n```\n\n## Test / Usage\n\n```\ncurl -d '{\"body\":\"new contrib from toto: [44](http://radio.localhost/map/#44)\", \"key\": \"secret\"}' \\\n 'http://matrixwebhook.localhost/!DPrUlnwOhBEfYwsDLh:matrix.org'\n```\n\n(or localhost:4785 without docker)\n\n### For Github\n\nAdd a JSON webhook with `?formatter=github`, and put the `API_KEY` as secret\n\n### For Grafana\n\nAdd a webhook with an URL ending with `?formatter=grafana&key=API_KEY`\n\n### For Gitlab\n\nAt the group level, Gitlab does not permit to setup webhooks. A workaround consists to use Google\nChat or Microsoft Teams notification integration with a custom URL (Gitlab does not check if the url begins with the normal url of the service).\n\n#### Google Chat\n\nAdd a Google Chat integration with an URL ending with `?formatter=gitlab_gchat&key=API_KEY`\n\n#### Microsoft Teams\n\nAdd a Microsoft Teams integration with an URL ending with `?formatter=gitlab_teams&key=API_KEY`\n\n#### Gitlab Webhook\n\nAt the project level, you can add a webhook with an URL ending with `?formatter=gitlab_webhook` and put your `API_KEY`\nas secret token. Not yet as pretty as other formatters, contributions welcome !\n\n### Github Release Notifier\n\nTo 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)](https://github.com/femtopixel/github-release-notifier).\n\n## Test room\n\n[#matrix-webhook:tetaneutral.net](https://matrix.to/#/!DPrUlnwOhBEfYwsDLh:matrix.org)\n\n## Unit tests\n\n```\ndocker-compose -f test.yml up --exit-code-from tests --force-recreate --build\n```\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "Post a message to a matrix room with a simple HTTP POST",
"version": "3.9.1",
"project_urls": {
"Homepage": "https://github.com/nim65s/matrix-webhook",
"Repository": "https://github.com/nim65s/matrix-webhook.git",
"changelog": "https://github.com/nim65s/matrix-webhook/blob/master/CHANGELOG.md"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "003a19d11321fba4244f899b4d8fcd1193292c8bde71c294d98a30d234ffe46b",
"md5": "dc914e0b4db78522e63ab90ac2ce3f0e",
"sha256": "e8c7e573157360bee511ab08978e2a1e9a340c8a1d1691a70c01a8526df98505"
},
"downloads": -1,
"filename": "matrix_webhook-3.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc914e0b4db78522e63ab90ac2ce3f0e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 10329,
"upload_time": "2024-03-08T23:32:43",
"upload_time_iso_8601": "2024-03-08T23:32:43.622540Z",
"url": "https://files.pythonhosted.org/packages/00/3a/19d11321fba4244f899b4d8fcd1193292c8bde71c294d98a30d234ffe46b/matrix_webhook-3.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e6054918e23756d502fff2d46871a2fa7339151be33dedb4445fe21aab35d999",
"md5": "a2f4bf6fa9e042951b25506faf12bdca",
"sha256": "0dca8382c9b66a5e0097d4d0675ac5801ac33c1b66e29c2932515d1ff6aff010"
},
"downloads": -1,
"filename": "matrix_webhook-3.9.1.tar.gz",
"has_sig": false,
"md5_digest": "a2f4bf6fa9e042951b25506faf12bdca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 9933,
"upload_time": "2024-03-08T23:32:44",
"upload_time_iso_8601": "2024-03-08T23:32:44.749795Z",
"url": "https://files.pythonhosted.org/packages/e6/05/4918e23756d502fff2d46871a2fa7339151be33dedb4445fe21aab35d999/matrix_webhook-3.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-08 23:32:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nim65s",
"github_project": "matrix-webhook",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "matrix-webhook"
}
JSON
