From e79b26a3b4ab376a3eea8296887c6a632d3c14b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?marcin=20miko=C5=82ajczak?= <git@mkljczk.pl>
Date: Tue, 15 Aug 2023 00:13:44 +0200
Subject: [PATCH] Add documentation for webhooks API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: marcin mikołajczak <git@mkljczk.pl>
---
 docs/development/API/admin_api.md             | 89 +++++++++++++++++++
 .../operations/admin/webhook_operation.ex     |  2 +-
 2 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/docs/development/API/admin_api.md b/docs/development/API/admin_api.md
index 7d31ee262..ed3d68d6e 100644
--- a/docs/development/API/admin_api.md
+++ b/docs/development/API/admin_api.md
@@ -1751,3 +1751,92 @@ Note that this differs from the Mastodon API variant: Mastodon API only returns
 ```json
 {}
 ```
+
+## `GET /api/v1/pleroma/admin/webhooks`
+
+### List webhooks
+
+- Method: `GET`
+- Response:
+
+```json
+[
+  {
+    "enabled": true,
+    "id": "2",
+    "events": ["account.created"],
+    "url": "https://webhook.example/",
+    "secret": "eb85d4ccd8510e78f912743949dc354e8146987d",
+    "updated_at": "2022-10-29T17:44:16.000Z",
+    "created_at": "2022-10-29T17:44:13.000Z"
+  }
+]
+```
+
+## `GET /api/v1/pleroma/admin/webhooks/:id`
+
+### Get an individual webhook
+
+- Method: `GET`
+- Params:
+  - `id`: **string** Webhook ID
+- Response: A webhook
+
+## `POST /api/v1/pleroma/admin/webhooks`
+
+### Create a webhook
+
+- Method: `POST`
+- Params:
+  - `url`: **string** Webhook URL
+  - *optional* `events`: **[string]** Types of events to trigger on (`account.created`, `report.created`)
+  - *optional* `enabled`: **boolean** Whether webhook is enabled
+- Response: A webhook
+
+## `PATCH /api/v1/pleroma/admin/webhooks/:id`
+
+### Update a webhook
+
+- Method: `PATCH`
+- Params:
+  - `id`: **string** Webhook ID
+  - *optional* `url`: **string** Webhook URL
+  - *optional* `events`: **[string]** Types of events to trigger on (`account.created`, `report.created`)
+  - *optional* `enabled`: **boolean** Whether webhook is enabled
+- Response: A webhook
+
+## `DELETE /api/v1/pleroma/admin/webhooks/:id`
+
+### Delete a webhook
+
+- Method: `DELETE`
+- Params:
+  - `id`: **string** Webhook ID
+- Response: A webhook
+
+## `POST /api/v1/pleroma/admin/webhooks/:id/enable`
+
+### Activate a webhook
+
+- Method: `POST`
+- Params:
+  - `id`: **string** Webhook ID
+- Response: A webhook
+
+## `POST /api/v1/pleroma/admin/webhooks/:id/disable`
+
+### Deactivate a webhook
+
+- Method: `POST`
+- Params:
+  - `id`: **string** Webhook ID
+- Response: A webhook
+
+## `POST /api/v1/pleroma/admin/webhooks/:id/rotate_secret`
+
+### Rotate webhook signing secret
+
+- Method: `POST`
+- Params:
+  - `id`: **string** Webhook ID
+- Response: A webhook
diff --git a/lib/pleroma/web/api_spec/operations/admin/webhook_operation.ex b/lib/pleroma/web/api_spec/operations/admin/webhook_operation.ex
index 0c4e1797f..c83caa555 100644
--- a/lib/pleroma/web/api_spec/operations/admin/webhook_operation.ex
+++ b/lib/pleroma/web/api_spec/operations/admin/webhook_operation.ex
@@ -163,7 +163,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.WebhookOperation do
         "id" => "1",
         "url" => "https://example.com/webhook",
         "events" => ["report.created"],
-        "secret" => "D3D8CF4BC11FD9C41FD34DCC38D282E451C8BD34",
+        "secret" => "d3d8cf4bc11fd9c41fd34dcc38d282e451c8bd34",
         "enabled" => true,
         "created_at" => "2022-06-24T16:19:38.523Z",
         "updated_at" => "2022-06-24T16:19:38.523Z"