Document build triggers

3 files changed, 30 insertions, 2 deletions

diff --git a/builds.sr.ht/api.md b/builds.sr.ht/api.md
index 7e74bb0..48e6213 100644
--- a/builds.sr.ht/api.md
+++ b/builds.sr.ht/api.md
@@ -43,6 +43,8 @@ Inserts a new job into the job queue.
                                       (optional - defaults to true)
     }
 
+See also: [Build triggers](triggers.md)
+
 ## GET /api/jobs/:id
 
 Gets information about a job by its ID.
diff --git a/builds.sr.ht/manifest.md b/builds.sr.ht/manifest.md
index bd4a159..7e51006 100644
--- a/builds.sr.ht/manifest.md
+++ b/builds.sr.ht/manifest.md
@@ -102,8 +102,9 @@ Each task is run in a separate login session, so if you modify the groups of the
 *list* (of *trigger*)
 
 A list of triggers to execute post-build, which can be used to send emails
-or do other post-build tasks. This uses the same structure as triggers in
-[the API](/builds.sr.ht/api.md#post-apijobs), but as YAML rather than JSON.
+or do other post-build tasks.
+
+See also: [Build triggers](triggers.md)
 
 ## environment
 
diff --git a/builds.sr.ht/triggers.md b/builds.sr.ht/triggers.md
new file mode 100644
index 0000000..09a7aff
--- /dev/null
+++ b/builds.sr.ht/triggers.md
@@ -0,0 +1,25 @@
+At the end of a job or a job group, you can execute triggers based on the
+outcome of the job. The basic format is (in YAML or JSON):
+
+    {
+        "action": "trigger type",
+        "condition": "when to execute this trigger",
+        [...action-specific configuration...]
+    }
+
+Condition may be one of the following:
+
+- **always**: execute the trigger after every build
+- **failure**: execute the trigger after a failed build
+- **success**: execute the trigger after a successful build
+
+The following actions are available:
+
+## webhook
+
+Submits the job status (as it would be returned by GET /api/jobs/:id) as a POST
+request to a specified URL.
+
+*Configuration*
+
+- **url**: The URL to submit the HTTP request to