Adding webhooks to Matrix
Tags: matrix, docker, traefik, webhooks
Published: 2019-02-28 15:32:19

---
title: Adding webhooks to Matrix
published: true
tags: matrix,docker,traefik,webhooks
canonical_url: https://jonnev.se/adding-webhooks-to-matrix/
---

 ![Adding webhooks to Matrix](https://jonnev.se/content/images/2019/02/Screenshot-2019-02-26-at-00.03.38-1.png)

Now that you got your [homeserver](https://dev.to/joenas/matrix-homeserver-synapse-v09911-with-traefik-35ja) you want some integrations right? Webhooks seems like a great place to start - it's fairly easy to set up and the use cases are virtually unlimited.

I have a couple of scenarios in [Huginn](https://dev.to/joenas/my-two-favourite-services-30km-temp-slug-492995) for posting tomorrows weather, top voted posts from various [subreddits](https://www.reddit.com/me/m/devsnack/) and alerts from Grafana, to mention a few.

In this guide we will use an [application service](https://matrix.org/docs/guides/application_services.html) (👈 _read this if you haven't_) called [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) to be able to add webhooks to a room by just issuing a command. It has a Docker image so it fits right into my standard Traefik setup. If your Synapse isn't set up like [mine](https://dev.to/joenas/matrix-homeserver-synapse-v09911-with-traefik-35ja) you'll have to make some adjustments.

## Setup

First let's get the files we need for the appservice.

```
cd /opt/matrix # or wherever your stuff is 
mkdir matrix-appservice-webhooks
cd matrix-appservice-webhooks
curl https://raw.githubusercontent.com/turt2live/matrix-appservice-webhooks/master/config/database.json -o database.json
curl https://raw.githubusercontent.com/turt2live/matrix-appservice-webhooks/master/config/sample.yaml -o config.yaml

```

Then we replace paths in `database.json`...

```
sed -i 's/db\//\/data\//' database.json

```

... so that it looks like this.

```
{
  "defaultEnv": {
    "ENV": "NODE_ENV"
  },
  "development": {
    "driver": "sqlite3",
    "filename": "/data/development.db"
  },
  "production": {
    "driver": "sqlite3",
    "filename": "/data/production.db"
  }
}

```

We edit `config.yaml`...

```
nano config.yaml

```

... and put in the (internal) URL to Synapse - accessible via our Docker network - the public URL for our webhooks and our Matrix domain name.

```
homeserver:
  # The name here is from docker-compose.yaml
  url: "http://synapse:8008"

  # Domain for you matrix server, with subdomain if needed
  domain: "example.com"

web:
  # This domain will be proxied via Traefik
  hookUrlBase: 'https://webhooks.example.com'
  # Because we're in a container
  bind: '0.0.0.0'

```

☝️ I only included the settings that needs to be changed for this guide. Edit the others according to comments in the file and remember to replace `example.com`.

### Registration file

Then we need to generate a registration file to add to Synapse via `homeserver.yaml`.

```
docker run --rm \
  -v /opt/matrix/matrix-appservice-webhooks:/data \
  turt2live/matrix-appservice-webhooks \
  node index.js -r \
  -f /data/appservice-registration-webhooks.yaml \
  -u "http://webhooks:9000" \
  -c /data/config.yaml

```

Now you should have a file called `appservice-registration-webhooks.yaml` in your appservice directory. Copy that file to your Synapse dir (`/opt/matrix/synapse` in my case).

```
sudo cp appservice-registration-webhooks.yaml ../synapse

```

Add/edit the line below in your `homeserver.yaml`, so that Synapse is aware of the appservice.

```
app_service_config_files: ['/data/appservice-registration-webhooks.yaml']

```

### docker-compose

Time to add the container to our `docker-compose.yaml`.

```
  webhooks:
    image: turt2live/matrix-appservice-webhooks
    restart: unless-stopped
    depends_on:
      - synapse
    networks:
      - web
      - default
    volumes:
      - "/opt/matrix/matrix-appservice-webhooks:/data"
    labels:
      - "traefik.enable=true"
      - "traefik.frontend.rule=Host:webhooks.example.com"
      - "traefik.port=9000"
      - "traefik.docker.network=web"

```

☝️ If you've followed my previous guide, this should be enough. Remember to replace `example.com`.

Now we're all set and ready to start the service.

```
docker-compose up -d webhooks
docker-compose restart synapse

```

### Adding hook to a room

Go to a room where you want to have a webhook, invite the bot user `@_webhook:example.com` (adjust handle if you changed it in `config.yaml`), send the message `!webhook` in the room and you should see something like this 👇

![Adding webhooks to Matrix](https://jonnev.se/content/images/2019/02/Screenshot-2019-02-26-at-00.03.38.png)

### Posting them hooks

Test your webhook with an app like [Insomnia](https://insomnia.rest) / [Postman](https://www.getpostman.com) or just use `curl`.

```
curl --header "Content-Type: application/json" \
     --data '{
       "text": "Hello world!",
       "format": "plain",
       "displayName": "My Cool Webhook",
       "avatarUrl": "http://i.imgur.com/IDOBtEJ.png"
     }' \
   YOUR_URL

```

![Adding webhooks to Matrix](https://jonnev.se/content/images/2019/02/Screenshot-2019-02-26-at-00.11.57.png)

### Updating hooks

The first time you post the appservice will invite a _virtual user_ with the name and avatar you set. If you change `displayName` on succeeding posts another user will join and if you change `avatarUrl` but not `displayName` the avatar will update.

That's it! Have fun 🎉