Slack-compatible webhooks for matrix
Branch: master
Clone or download
Latest commit 7753eef Oct 20, 2018


TravisCI badge

Slack-compatible webhooks for Matrix. Talk about it on Matrix:


Invite the webhook bridge to your room ( and send the message !webhook. The bridge bot will then send you a link to send messages to in a private message. You must be able to configure the room in order to set up webhooks.

JSON Body (for posting messages)

  "text": "Hello world!",
  "format": "plain",
  "displayName": "My Cool Webhook",
  "avatarUrl": ""

Format can be plain or html. Emoji will be converted automatically(:heart: becomes ❤); set the emoji property to false to disable this conversion. To send a notice or emote, add "msgtype" : "notice" or "msgtype" : "emote" in your request.


Before you begin: A matrix homeserver and Node 9 or higher are required.

  1. Clone this repository and install the dependencies

    git clone
    cd matrix-appservice-webhooks
    npm install
  2. Copy config/sample.yaml to config/config.yaml and fill in the appropriate fields

  3. Generate the registration file

    node index.js -r -u "http://localhost:9000" -c config/config.yaml

    Note: The default URL to run the appservice is http://localhost:9000. If you have other appservices, or other requirements, pick an appropriate hostname and port.

  4. Copy/symlink the registration file to your Synapse directory

    cd ~/.synapse
    ln -s ../matrix-appservice-webhooks/appservice-registration-webhooks.yaml appservice-registration-webhooks.yaml
  5. Add the registration file to your homeserver.yaml

    app_service_config_files: ["appservice-registration-webhooks.yaml"]
  6. Restart Synapse (synctl restart, for example)


Using the port specified during the install (9000 by default), use node index.js -p 9000 -c config/config.yaml -f appservice-registration-webhooks.yaml from the repository directory.

The bridge should start working shortly afterwards.


A Docker image of the bridge is available to host the bridge yourself. The image can be built yourself with docker build -t matrix-appservice-webhooks . or you can use the image on

docker run -p 9000:9000 -v /path/to/webhooks/dir:/data turt2live/matrix-appservice-webhooks

The /path/to/webhooks/dir should have an appservice-registration-webhooks.yaml file, config.yaml, and database.json. Additional bridge-related data will be stored here.

Example appservice-registration-webhooks.yaml

id: webhooks
    - exclusive: true
      regex: '@_webhook.*'
  aliases: []
  rooms: []
url: 'http://localhost:9002'  # you may need to change this (this should point at the bridge)
sender_localpart: _webhook
rate_limited: false
protocols: null