Document build triggers

1 files changed, 25 insertions, 0 deletions

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