diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md
index b315aeff..80e73112 100644
--- a/doc/manual/src/SUMMARY.md
+++ b/doc/manual/src/SUMMARY.md
@@ -8,6 +8,7 @@
 - [Plugins](./plugins/README.md)
   - [Declarative Projects](./plugins/declarative-projects.md)
 - [Using the external API](api.md)
+- [Webhooks](webhooks.md)
 - [Monitoring Hydra](./monitoring/README.md)
 
 ## Developer's Guide
diff --git a/doc/manual/src/plugins/README.md b/doc/manual/src/plugins/README.md
index 25ea6e3a..b5486fdb 100644
--- a/doc/manual/src/plugins/README.md
+++ b/doc/manual/src/plugins/README.md
@@ -99,7 +99,7 @@ GitHub following a certain naming scheme.
 
 ### Configuration options
 
-- `github_endpoint`
+- `github_endpoint` (defaults to https://api.github.com)
 - `github_authorization.<repo-owner>`
 
 ## Github status
@@ -111,7 +111,7 @@ Sets GitHub CI status.
 - `githubstatus.[].jobs`
 
 Regular expression for jobs to match in the format `project:jobset:job`.
-Defaults to `*:*:*`.
+This field is required and has no default value.
 
 - `githubstatus.[].excludeBuildFromContext`
 
@@ -140,15 +140,18 @@ status we want to report. Can be repeated.
 
 Verbatim contents of the Authorization header. See
 [GitHub documentation](https://developer.github.com/v3/#authentication) for
-details.
+details. This field is only used if `github_authorization.<repo-owner>` is not set.
+
 
 ### Example
 
 ```xml
 <githubstatus>
   jobs = test:pr:build
+  ## This example will match all jobs
+  #jobs = .*
   inputs = src
-  authorization = Basic notgivingyoumypasswordosorry
+  authorization = Bearer gha-secret😱secret😱secret😱
   excludeBuildFromContext = 1
 </githubstatus>
 ```
diff --git a/doc/manual/src/webhooks.md b/doc/manual/src/webhooks.md
new file mode 100644
index 00000000..2b26cd61
--- /dev/null
+++ b/doc/manual/src/webhooks.md
@@ -0,0 +1,13 @@
+# Webhooks
+
+Hydra can be notified by github's webhook to trigger a new evaluation when a
+jobset has a github repo in its input.
+To set up a github webhook go to `https://github.com/<yourhandle>/<yourrepo>/settings` and in the `Webhooks` tab
+click on `Add webhook`.
+
+- In `Payload URL` fill in `https://<your-hydra-domain>/api/push-github`.
+- In `Content type` switch to `application/json`.
+- The `Secret` field can stay empty.
+- For `Which events would you like to trigger this webhook?` keep the default option for events on `Just the push event.`.
+
+Then add the hook with `Add webhook`.