add webhooks reference

Author: guimachiavelli

.code-samples.meilisearch.yaml

@@ -1479,6 +1479,32 @@ export_post_1: |-
         }
       }
     }'
+webhooks_get_1: |-
+  curl \
+    -X GET 'MEILISEARCH_URL/webhooks'
+webhooks_post_1: |-
+  curl \
+    -X POST 'MEILISEARCH_URL/webhooks' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "url": "WEBHOOK_TARGET_URL",
+      "headers": {
+        "authorization": "SECURITY_KEY",
+        "referer": "https://example.com"
+      }
+    }'
+webhooks_patch_1: |-
+  curl \
+    -X PATCH 'MEILISEARCH_URL/webhooks/WEBHOOK_UUID' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "header": {
+        "referer": null
+      }
+    }'
+webhooks_delete_1: |-
+  curl \
+    -X DELETE 'MEILISEARCH_URL/webhooks'
 
 ### Code samples for experimental features
 experimental_get_metrics_1: |-

docs.json

@@ -350,7 +350,8 @@
                   "reference/api/experimental_features",
                   "reference/api/metrics",
                   "reference/api/logs",
-                  "reference/api/export"
+                  "reference/api/export",
+                  "reference/api/webhooks"
                 ]
               },
               {

reference/api/webhooks.mdx

@@ -0,0 +1,137 @@
+---
+title: Webhooks
+description: Use the /webhooks to trigger automatic workflows when Meilisearch finishes processing tasks.
+---
+
+import { RouteHighlighter } from '/snippets/route_highlighter.mdx'
+
+import CodeSamplesWebhooksGet1 from '/snippets/samples/code_samples_webhooks_get_1.mdx';
+import CodeSamplesWebhooksPost1 from '/snippets/samples/code_samples_webhooks_post_1.mdx';
+import CodeSamplesWebhooksPatch1 from '/snippets/samples/code_samples_webhooks_patch_1.mdx';
+import CodeSamplesWebhooksDelete1 from '/snippets/samples/code_samples_webhooks_delete_1.mdx';
+
+Use the `/webhooks` to trigger automatic workflows when Meilisearch finishes processing tasks.
+
+## The webhook object
+
+```json
+{
+  "uuid": "V4_UUID_GENERATED_BY_MEILISEARCH",
+  "url": "WEBHOOK_NOTIFICATION_TARGET_URL",
+  "headers": {
+    "HEADER": "VALUE",
+  },
+  "isEditable": false
+}
+```
+
+- `uuid`: a v4 uuid Meilisearch automatically generates when you create a new webhook
+- `url`: a string indication the URL Meilisearch should notify whenever it completes a task, required
+- `headers`: an object with HTTP headers and their values, optional, often used for authentication
+- `isEditable`: read-only Boolean field indicating whether you can edit the webhook. Meilisearch automatically sets this to false for its internal webhooks
+
+## The webhook payload
+
+When Meilisearch finishes processing a task, it sends the relevant [task object](/reference/api/tasks#task-object) to all configured webhooks.
+
+## Get all webhooks
+
+<RouteHighlighter method="GET" path="/healths" />
+
+Get a list of all webhooks configured in the current Meilisearch instance.
+
+### Example
+
+<CodeSamplesWebhooksGet1 />
+
+#### Response: `200 OK`
+
+```json
+{
+  "results": [
+    {
+      "uuid": "UUID_V4",
+      "url": "WEBHOOK_TARGET_URL",
+      "headers": {
+        "HEADER": "VALUE",
+      },
+      "isEditable": false
+    },
+    {
+      "uuid": "UUID_V4",
+      "url": "WEBHOOK_TARGET_URL",
+      "headers": null,
+      "isEditable": true
+    }
+  ]
+}
+```
+
+## Create new webhook
+
+<RouteHighlighter method="POST" path="/webhooks" />
+
+Create a new webhook. When Meilisearch finishes processing a task, it sends the relevant [task object](/reference/api/tasks#task-object) to all configured webhooks.
+
+### Example
+
+<CodeSamplesWebhooksPost1 />
+
+#### Response: `200 OK`
+
+```json
+{
+  "uuid": "627ea538-733d-4545-8d2d-03526eb381ce",
+  "url": "WEBHOOK_TARGET_URL",
+  "headers": {
+    "authorization": "SECURITY_KEY",
+    "referer": "https://example.com",
+  },
+  "isEditable": true
+}
+```
+
+## Update webhook
+
+<RouteHighlighter method="PATCH" path="/webhooks/{uuid}" />
+
+Update the configuration for the specified webhook. To remove a field, set its value to `null`.
+
+<Note>
+It is not possible to edit webhooks whose `isEditable` field is set to `false`.
+
+Meilisearch Cloud may create internal webhooks to support features such as Analytics and monitoring. These webhooks are always `isEditable: false`.
+</Note>
+
+### Example
+
+<CodeSamplesWebhooksPatch1 />
+
+#### Response: `200 OK`
+
+```json
+{
+  "uuid": "627ea538-733d-4545-8d2d-03526eb381ce",
+  "url": "WEBHOOK_TARGET_URL",
+  "headers": {
+    "authorization": "SECURITY_KEY"
+  },
+  "isEditable": true
+}
+```
+
+## Delete webhook
+
+<RouteHighlighter method="DELETE" path="/webhooks/{uuid}" />
+
+Delete a webhook and stop sending task completion data to the target URL.
+
+<Note>
+It is not possible to delete webhooks whose `isEditable` field is set to `false`.
+</Note>
+
+### Example
+
+<CodeSamplesWebhooksDelete1 />
+
+#### Response: `204 No Content`