Add documentation for git.sr.ht webhooks

1 files changed, 89 insertions, 0 deletions

diff --git a/git.sr.ht/api.md b/git.sr.ht/api.md
index 2a847a0..35a37c8 100644
--- a/git.sr.ht/api.md
+++ b/git.sr.ht/api.md
@@ -296,3 +296,92 @@ for binary blobs.
 
 Equivalent to [/api/:username/repos/:name/blob/:id](#GET-apiusernamereposnameblobid),
 implies the authenticated user.
+
+## Webhooks
+
+### /api/user/...
+
+Webhook for user events. Includes the [standard webhook
+endpoints](../api-conventions.md#webhooks)
+
+#### repo:create
+
+Issued when the user creates a new repository.
+
+**OAuth scope**: `info:read`
+
+**Request body**
+
+The new [repository resource](#repository-resource).
+
+#### repo:update
+
+Issued when the user updates repository details, such as name or description.
+
+**OAuth scope**: `info:read`
+
+**Request body**
+
+The updated [repository resource](#repository-resource).
+
+**Notes**
+
+- When the name of the repository changes, the URL at which its webhooks are
+  managed is updated accordingly. Users of the repository webhooks may wish to
+  act accordingly. The ID will remain consistent.
+
+#### repo:delete
+
+Issued when the user deletes a repository.
+
+**OAuth scope**: `info:read`
+
+**Request body**
+
+```json
+{
+  "id": integer ID of the affected repository resource
+}
+```
+
+### /api/:username/repos/:name/...
+
+Webhook for repository events. Includes the [standard webhook
+endpoints](../api-conventions.md#webhooks). You may pass an additional parameter
+to the webhook creation endpoint named "sync", which shall be a boolean value.
+
+#### repo:post-update
+
+Called after refs have been updated. If the `sync` flag on this webhook is set
+to true, the webhook is invoked *during* `git-receive-pack`'s [`post-update`
+hook][post-update] and the response text is printed to the console of the user
+executing `git push`. Your server has 5 seconds to respond to the HTTP request.
+
+[post-update]: https://git-scm.com/docs/git-receive-pack#_post_update_hook
+
+**OAuth scope**: `data:read`
+
+**Request body**
+
+```json
+{
+  "push": "uuid assigned to this push event",
+  "pusher": { user resource },
+  "refs": [
+    {
+      "name": "updated ref, e.g. refs/heads/master",
+      "annotated_tag": {
+        "name": "tag name",
+        "message": "tag message"
+      }, # may not be present
+      "old": {
+        commit resource this ref used to refer to, or null in the case of new
+        refs
+      },
+      "new": {
+        commit resource this ref now refers to
+      }
+    }
+  ]
+}
+```