From c2696e8fa733606745b042f39ade7419ebb8d0f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Marten?= <bjoern.marten@netresearch.de>
Date: Fri, 10 Jan 2020 14:53:33 +0100
Subject: [PATCH] Add appservice-webhooks configuration documentation

---
 ...ing-playbook-bridge-appservice-webhooks.md | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 docs/configuring-playbook-bridge-appservice-webhooks.md

diff --git a/docs/configuring-playbook-bridge-appservice-webhooks.md b/docs/configuring-playbook-bridge-appservice-webhooks.md
new file mode 100644
index 00000000..da0e206d
--- /dev/null
+++ b/docs/configuring-playbook-bridge-appservice-webhooks.md
@@ -0,0 +1,58 @@
+# Setting up Appservice Webhooks (optional)
+
+The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you.
+
+Setup Instructions:
+
+loosely based on [this](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md)
+
+1. All you basically need is to adjust your `inventory/host_vars/matrix.<domain-name>/host-vars.yml`:
+    ```yaml
+    matrix_appservice_webhooks_enabled: true
+    matrix_appservice_webhooks_api_secret: '<your_secret>'
+    ```
+
+2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
+you can adjust this in `inventory/host_vars/matrix.<domain-name>/host-vars.yml` as well.
+<br>
+*Note*: default value is: `info` and availabe log levels are : `info, verbose`
+
+    ```yaml
+    matrix_appservice_webhooks_log_level: '<log_level>'
+    ```
+
+3. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
+
+4. Invite the bridge bot user to your room:
+    - either with:
+      ```
+      /invite @_webhook:matrix.<domain.name>
+      ```
+        *Note*: Make sure you have administration permissions in your room
+    - or simply add the bridge bot to a private channel (personal channels imply you being an administrator)
+
+5. Send a message to the bridge bot in order to receive a private message including the webhook link.
+    ```
+    !webhook
+    ```
+
+6. The JSON body for posting messages will have to look like this:
+    ```
+    {
+        "text": "Hello world!",
+        "format": "plain",
+        "displayName": "My Cool Webhook",
+        "avatarUrl": "http://i.imgur.com/IDOBtEJ.png"
+    }
+    ```
+   - You can test this via curl like so:
+     ```
+     curl --header "Content-Type: application/json" \
+     --data '{
+     "text": "Hello world!",
+     "format": "plain",
+     "displayName": "My Cool Webhook",
+     "avatarUrl": "http://i.imgur.com/IDOBtEJ.png"
+     }' \
+     <the link you've gotten in 5.>
+     ```