BookStack Code Mirror - website/blob - content/docs/admin/email-webhooks.md

   1 +++
   2 title = "Email & Webhooks"
   3 date = "2021-12-21"
   4 type = "admin-doc"
   5 slug = "email-webhooks"
   6 aliases = ["email-config"]
   7 +++
   8
   9 Within BookStack email is used in various ways relating to user management & authentication.
  10 Outgoing webhooks are available as a mechanism to extend BookStack or notify in an event-driven manner.
  11
  12 {{<toc>}}
  13
  14 ---
  15
  16 ### Email Configuration
  17
  18 BookStack sends out emails for a range of purposes such as email-address confirmation & "forgot password" flows.
  19 Both SMTP and Sendmail (Linux Sendmail) are supported email mechanisms.
  20
  21 #### SMTP
  22
  23 To get up and running with SMTP you will need to add, or set, the following variables in your `.env` file:
  24
  25 ```bash
  26 MAIL_DRIVER=smtp
  27
  28 # SMTP server host address
  29 MAIL_HOST=smtp.provider.tld
  30
  31 # SMTP server port
  32 # Using port 465 will force connections to be via TLS
  33 MAIL_PORT=587
  34
  35 # Connection encryption to use
  36 # Valid values are: tls, null
  37 # Using 'tls' will require either TLS or STARTTLS to be used.
  38 # When using 'null' STARTTLS will still be attempted if announced
  39 # as supported by your SMTP server.
  40 # Using port 465 above will force connections to be via TLS.
  41 MAIL_ENCRYPTION=tls
  42
  43 # Authentication details for your SMTP service
  44 [email protected]
  45 MAIL_PASSWORD=onlyifneeded
  46
  47 # The "from" email address for outgoing email
  48 [email protected]
  49
  50 # The "from" name used for outgoing email
  51 MAIL_FROM_NAME=BookStack
  52 ```
  53
  54 ##### Connection TLS/SSL Certificate Verification
  55
  56 In some cases your SMTP server may be using a private/self-signed TLS/SSL certificate that would usually fail certificate verification.
  57 In these cases its common for that certificate (Or its CA) to be added to the BookStack's host trusted certificate database.
  58 If that's not possible, you can alternatively disable SSL/TLS certificate verification for mail sending
  59  by adding this setting to your `.env` file:
  60
  61 ```bash
  62 # Verify SSL/TLS certificates during SMTP sending
  63 # WARNING: Disabling verification using a 'false' value
  64 # can make you vulnerable to MITM attacks
  65 MAIL_VERIFY_SSL=false
  66 ```
  67
  68 #### Sendmail
  69
  70 The `sendmail` drivers uses the sendmail application on the host system. By default it will call `/usr/sbin/sendmail -bs` although this is configurable.
  71
  72 To enable this option you can set the following in your `.env` file:
  73
  74 ```bash
  75 MAIL_DRIVER=sendmail
  76
  77 # The "from" email address for outgoing email
  78 [email protected]
  79
  80 # The "from" name used for outgoing email
  81 MAIL_FROM_NAME=BookStack
  82
  83 # The command to use for calling sendmail
  84 MAIL_SENDMAIL_COMMAND="/usr/sbin/sendmail -bs"
  85 ```
  86
  87 #### Debugging Email
  88
  89 You can follow the instructions provided in the [debugging documentation page](/docs/admin/debugging/)
  90 to help gain more details about issues you may come across. Within the "Settings > Maintenance" area of
  91 BookStack you can find a "Send a Test Email" action which provides a quick & easy way to send emails
  92 after changing your configuration. This action will also attempt to capture any errors thrown and display them.
  93
  94 ---
  95
  96 ### Outgoing Webhooks
  97
  98 Webhooks can be configured in the "Settings > Webhooks" area of your BookStack instance.
  99 An example of the POST data format is shown when creating or editing a webhook.
 100
 101 The webhook data is "Slack Compatible" in respect to having a `text` property containing a human-readable description
 102 of the event. Services such as [Discord](https://discord.com/developers/docs/resources/webhook#execute-slackcompatible-webhook), [Zulip](https://zulip.com/integrations/doc/slack_incoming) and Teams, upon many others, have options to support this format.
 103
 104 A video guide on BookStack webhooks, including usage with Discord and HomeAssistant, [can be found here](https://foss.video/w/xu4T7mafyLqkLU1VTgNaCV).
 105
 106 The running of webhooks can slow down a system due to the required additional processing time.
 107 See the [async action handling](#async-action-handling) section below to details on running webhooks
 108 in a background process to improve performance.
 109
 110 ---
 111
 112
 113 ### Async Action Handling
 114
 115 Actions like sending email or triggering webhooks are performed synchronously by default which can
 116 slow down page loading when those actions are triggered. These actions can instead be processed asynchronously
 117 so they're handled in the background to prevent slowing down the request. This requires a config change
 118 and a queue worker process to handle these background jobs:
 119
 120 #### Config Change
 121
 122 Within your `.env` file add or update (if already existing) the following option then save the file.
 123
 124 ```bash
 125 QUEUE_CONNECTION=database
 126 ```
 127
 128 #### Queue Worker Process
 129
 130 The queue work process can be run via the following command from your BookStack installation directory:
 131
 132 ```bash
 133 php artisan queue:work --sleep=3 --tries=3
 134 ```
 135
 136 Ideally this needs to be ran continuously. The method of doing this may depend on your operating system
 137 and personal software preferences. On many modern Linux systems systemd is an appropriate method.
 138 The below unit file example can be used with systemd to run this process. Note, this is suited to
 139 Ubuntu 20.04 setups that have used our installation script. Details may need tweaking for other systems.
 140
 141 ```bash
 142 [Unit]
 143 Description=BookStack Queue Worker
 144
 145 [Service]
 146 User=www-data
 147 Group=www-data
 148 Restart=always
 149 ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600
 150
 151 [Install]
 152 WantedBy=multi-user.target
 153 ```
 154
 155 To configure systemd (On a Ubuntu 20.04 system) with the above unit you'd typically:
 156
 157 - Create a new `/etc/systemd/system/bookstack-queue.service` file containing the above content.
 158 - Run `systemctl daemon-reload` to discover the new service.
 159 - Run `systemctl enable bookstack-queue.service` to ensure the service starts at (re)boot.
 160 - Run `systemctl start bookstack-queue.service` to start the queue service.
 161
 162 Note: you may need to run the above commands with `sudo` if not acting as a privileged user.
 163
 164 You can then use `systemctl status bookstack-queue.service` to check the status of the queue worker.