when someone performs an action in the system (Updates page, Creates book etc..).
Webhooks can be found by an administrator in the application settings.
-!! Image of webhooks list
+
Webhooks can be triggered by any event that's tracked in the audit log. You can choose
specific events to trigger your webhooks or you can trigger upon any event.
-!! Image of webhook create view
+
When triggered, BookStack will send a HTTP POST JSON request to the provided endpoint
with a common set of details regarding the event. The general data format is shown when creating
Since webhooks need to make external HTTP requests, they have potential to slow down a system.
If you're introducing webhooks that'd be triggered we have a way to run these in the background to
-prevent user experience slowdowns. Details about this can be found in the docs here.
-
-!! TODO - Update above with link
+prevent user experience slowdowns. [Details about this can be found here](/docs/admin/email-webhooks/#async-action-handling).
### Copy Entire Chapters & Books
and/or pages in a single smooth action. Copy views will now show warnings to confirm
copy behavior within BookStack so the necessary considerations can be made.
-!! IMAGE OF COPY VIEW
+
These new abilities bring some great potential new workflow advancements, such as being
able to create "templated" books pre-configured with the right chapter & page structure
When creating or updating a role there are a lot of permissions to configure.
Creating a set of similar roles could be a time consuming experience.
As of v21.12 there's now a "Copy" action when viewing an existing role which
-will take you to the role create view with all fields filled as per the copied role:
+will take you to the role create view with all fields filled as per the copied role.
+
+
+
+### Audit Log IP Address Search
+
+The audit log has received another update thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/3081).
+It's now possible to search the audit log by IP address.
+The search is a prefix-match so you can search using just the starting
+portion if needing to search a range.
+
+
### Search API Updates
I recently produced a getting started guide for the local theme system which includes
registering custom commands:
-<iframe width="560" height="315" src="https://www.youtube.com/embed/YVbpm_35crQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+<iframe width="100%" height="360" src="https://www.youtube.com/embed/YVbpm_35crQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
### Translations
**Released in v21.12**
-
+* Added webhooks. ([#147](https://github.com/BookStackApp/BookStack/pull/147), [#3099](https://github.com/BookStackApp/BookStack/pull/3099))
+* Added ability to copy books, chapters & roles. ([#3118](https://github.com/BookStackApp/BookStack/pull/3118), [#1123](https://github.com/BookStackApp/BookStack/issues/1123))
+* Added audit log IP address search. Thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/3081). ([#3081](https://github.com/BookStackApp/BookStack/pull/3081))
+* Updated translations with latest Crowdin changes. ([#3117](https://github.com/BookStackApp/BookStack/pull/3117))
+* Fixed issue where non-ascii content could break search result previews. Thanks to [@Kristian-Krastev](https://github.com/BookStackApp/BookStack/pull/3113). ([#3113](https://github.com/BookStackApp/BookStack/pull/3113))
+* Fixed mismatched password validation rules across the application. ([#2237](https://github.com/BookStackApp/BookStack/issues/2237))
**Released in v21.11.1 through v21.11.3**
+++ /dev/null
-+++
-title = "Email Configuration"
-description = "Configuring BookStack to send email"
-date = "2020-03-14"
-type = "admin-doc"
-slug = "email-config"
-+++
-
-BookStack sends out emails for a range of purposes such as email-address confirmation & "forgot password" flows.
-The following mechanisms for sending mail are supported:
-
-1. SMTP
-3. Sendmail (Linux sendmail)
-
-## SMTP
-
-To get up and running with SMTP you will need to add, or set, the following variables in your `.env` file:
-
-```bash
-MAIL_DRIVER=smtp
-
-# Host, Port & Encryption mechanism to use
-MAIL_HOST=smtp.provider.tld
-MAIL_PORT=465
-MAIL_ENCRYPTION=tls
-
-# Authentication details for your SMTP service
-MAIL_USERNAME=user@provider.tld
-MAIL_PASSWORD=onlyifneeded
-
-# The "from" email address for outgoing email
-MAIL_FROM=noreply@yourdomain.tld
-
-# The "from" name used for outgoing email
-MAIL_FROM_NAME=BookStack
-```
-
-## Sendmail
-
-The `sendmail` drivers uses the sendmail application on the host system. It will call `/usr/sbin/sendmail -bs`.
-
-To enable this option you can set the following in your `.env` file:
-
-```bash
-MAIL_DRIVER=sendmail
-
-# The "from" email address for outgoing email
-MAIL_FROM=noreply@yourdomain.tld
-
-# The "from" name used for outgoing email
-MAIL_FROM_NAME=BookStack
-```
-
-## Debugging
-
-You can follow the instructions provided in the [debugging documentation page](/docs/admin/debugging/)
-to help gain more details about issues you may come across. Within the Settings > Maintenance area of
-BookStack you can find a "Send a Test Email" action which provides a quick & easy way to send emails
-after changing your configuration. This action will also attempt to capture any errors thrown and display them.
\ No newline at end of file
--- /dev/null
++++
+title = "Email & Webhooks"
+date = "2021-12-21"
+type = "admin-doc"
+slug = "email-webhooks"
+aliases = ["email-config"]
++++
+
+Within BookStack email is used in various ways relating to user management & authentication.
+Outgoing webhooks are available as a mechanism to extend BookStack or notify in an event-driven manner.
+
+- [Email Configuration](#email-configuration)
+- [Outgoing Webhooks](#outgoing-webhooks)
+- [Async Action Handling](#async-action-handling)
+
+---
+
+### Email Configuration
+
+BookStack sends out emails for a range of purposes such as email-address confirmation & "forgot password" flows.
+Both SMTP and Sendmail (Linux Sendmail) are supported email mechanisms.
+
+#### SMTP
+
+To get up and running with SMTP you will need to add, or set, the following variables in your `.env` file:
+
+```bash
+MAIL_DRIVER=smtp
+
+# Host, Port & Encryption mechanism to use
+MAIL_HOST=smtp.provider.tld
+MAIL_PORT=465
+MAIL_ENCRYPTION=tls
+
+# Authentication details for your SMTP service
+MAIL_USERNAME=user@provider.tld
+MAIL_PASSWORD=onlyifneeded
+
+# The "from" email address for outgoing email
+MAIL_FROM=noreply@yourdomain.tld
+
+# The "from" name used for outgoing email
+MAIL_FROM_NAME=BookStack
+```
+
+#### Sendmail
+
+The `sendmail` drivers uses the sendmail application on the host system. It will call `/usr/sbin/sendmail -bs`.
+
+To enable this option you can set the following in your `.env` file:
+
+```bash
+MAIL_DRIVER=sendmail
+
+# The "from" email address for outgoing email
+MAIL_FROM=noreply@yourdomain.tld
+
+# The "from" name used for outgoing email
+MAIL_FROM_NAME=BookStack
+```
+
+#### Debugging Email
+
+You can follow the instructions provided in the [debugging documentation page](/docs/admin/debugging/)
+to help gain more details about issues you may come across. Within the "Settings > Maintenance" area of
+BookStack you can find a "Send a Test Email" action which provides a quick & easy way to send emails
+after changing your configuration. This action will also attempt to capture any errors thrown and display them.
+
+---
+
+### Outgoing Webhooks
+
+Webhooks can be configured in the "Settings > Webhooks" area of your BookStack instance.
+An example of the POST data format is shown when creating or editing a webhook.
+
+The running on webhooks can slow down a system due to the required additional processing time.
+See the [async action handling](#async-action-handling) section below to details on running webhooks
+in a background process to improve performance.
+
+---
+
+
+### Async Action Handling
+
+Actions like sending email or triggering webhooks are done synchronously by default within BookStack which can
+slow down page loading when those actions are triggered. These actions can instead be processed asynchronously
+so they're handled in the background to prevent slowing down the request. This requires a config change
+and a queue worker process to handle these background jobs:
+
+#### Config Change
+
+Within your `.env` file add or update (if already existing) the following option then save the file.
+
+```bash
+QUEUE_CONNECTION=database
+```
+
+#### Queue Worker Process
+
+The queue work process can be run via the following command from your BookStack installation directory:
+
+```bash
+php artisan queue:work --sleep=3 --tries=3
+```
+
+Ideally this needs to be ran continuously. The method of doing this may depend on your operating system
+and personal software preferences. On many modern Linux systems systemd is an appropriate method.
+The below unit file example can be used with systemd to run this process. Note, this is suited to
+Ubuntu 20.04 setups that have used our installation script. Details may need tweaking for other systems.
+
+```bash
+[Unit]
+Description=BookStack Queue Worker
+
+[Service]
+User=www-data
+Group=www-data
+Restart=always
+ExecStart=/usr/bin/php /var/www/bookstack/artisan queue:work --sleep=3 --tries=1 --max-time=3600
+
+[Install]
+WantedBy=multi-user.target
+```
+
+To configure systemd (On a Ubuntu 20.04 system) with the above unit you'd typically:
+
+- Create a new `/etc/systemd/system/bookstack-queue.service` file containing the above content.
+- Run `systemctl daemon-reload` to discover the new service.
+- Run `systemctl enable bookstack-queue.service` to ensure the service starts at (re)boot.
+- Run `systemctl start bookstack-queue.service` to start the queue service.
+
+Note: you may need to run the above commands with `sudo` if not acting as a privileged user.
+You can then use `systemctl status bookstack-queue.service` to check the status of the queue worker.
\ No newline at end of file
--- /dev/null
+version https://git-lfs.github.com/spec/v1
+oid sha256:2056ad446986c4676641b23dbcc2a232b36ac0794fab529c9db93874b5d67660
+size 37600
--- /dev/null
+version https://git-lfs.github.com/spec/v1
+oid sha256:fc6eb1b4cd7f916891503545d46e033f0d8b474343fc979f7f319c8ba7c193e6
+size 36133
--- /dev/null
+version https://git-lfs.github.com/spec/v1
+oid sha256:f4fdfb46db2b1f6712ece2b63645a33ea7502198b7bb8c1688eb7f4ca929bb37
+size 16811
--- /dev/null
+version https://git-lfs.github.com/spec/v1
+oid sha256:a6dab6dc875237992f3406b748b08d62cdde590a93b9db8a00e73005f0fb657f
+size 47850
--- /dev/null
+version https://git-lfs.github.com/spec/v1
+oid sha256:6febc43feede386a14acb2cca65c7721e1cd8119076e278c9b4e3e9187b67463
+size 30570
<h4>Configuration</h4>
<ul>
- <li><a href="/docs/admin/email-config">Email Configuration</a></li>
+ <li><a href="/docs/admin/email-webhooks">Email & Webhooks</a></li>
<li><a href="/docs/admin/visual-customisation">Visual Customisation</a></li>
<li><a href="/docs/admin/language-config">Language & Locale</a></li>
<li><a href="/docs/admin/upload-config">File Uploads</a></li>
projects / website / commitdiff