From de466c8a3861128877834a73e057b0c039864414 Mon Sep 17 00:00:00 2001
From: gui machiavelli <gui@meilisearch.com>
Date: Fri, 2 Feb 2024 00:07:35 +0100
Subject: [PATCH] Webhook guide (#2698)

---
 config/sidebar-learn.json                |  5 ++
 learn/async/task_webhook.mdx             | 58 ++++++++++++++++++++++++
 learn/configuration/instance_options.mdx |  2 +-
 3 files changed, 64 insertions(+), 1 deletion(-)
 create mode 100644 learn/async/task_webhook.mdx

diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json
index 26dea1537b..c7f6eac487 100644
--- a/config/sidebar-learn.json
+++ b/config/sidebar-learn.json
@@ -111,6 +111,11 @@
         "source": "learn/async/managing_tasks.mdx",
         "label": "Managing the task database",
         "slug": "managing_tasks"
+      },
+      {
+        "source": "learn/async/task_webhook.mdx",
+        "label": "Using task webhooks",
+        "slug": "task_webhook"
       }
     ]
   },
diff --git a/learn/async/task_webhook.mdx b/learn/async/task_webhook.mdx
new file mode 100644
index 0000000000..905ef00454
--- /dev/null
+++ b/learn/async/task_webhook.mdx
@@ -0,0 +1,58 @@
+# Using task webhooks
+
+This guide teaches you how to use webhooks to notify a URL when Meilisearch completed a [task](/learn/async/asynchronous_operations).
+
+## Requirements
+
+- a command-line console
+- a self-hosted Meilisearch instance
+- a server configured to receive `POST` requests with an ndjson payload
+
+## Configure the webhook URL
+
+Restart your Meilisearch instance and provide the webhook URL to `--task-webhook-URL`:
+
+```sh
+meilisearch --task-webhook-url http://localhost:8000
+```
+
+You may also define the webhook URL with environment variables or in the configuration file with `MEILI_TASK_WEBHOOK_URL`.
+
+## Optional: configure an authorization header
+
+Depending on your setup, you may need to provide an authorization header. Provide it to `task-webhook-authorization-header`:
+
+```sh
+meilisearch --task-webhook-url http://localhost:8000 --task-webhook-authorization-header Bearer aSampleMasterKey
+```
+
+## Test the webhook
+
+A common asynchronous operation is adding or updating documents to an index. The following example adds a test document to our `books` index:
+
+```sh
+curl \
+  -X POST 'http://localhost:7700/indexes/books/documents' \
+  -H 'Content-Type: application/json' \
+  --data-binary '[
+    {
+      "id": 1,
+      "title": "Nuestra parte de noche",
+      "author": "Mariana Enríquez"
+    }
+  ]'
+```
+
+When Meilisearch finishes indexing this document, it will send a `POST` request the URL you configured with `--task-webhook-url`. The request body will be one or more task objects in [ndjson](https://github.com/ndjson/ndjson-spec) format:
+
+```ndjson
+{"uid":4,"indexUid":"books","status":"succeeded","type":"documentAdditionOrUpdate","canceledBy":null,"details.receivedDocuments":1,"details.indexedDocuments":1,"duration":"PT0.001192S","enqueuedAt":"2022-08-04T12:28:15.159167Z","startedAt":"2022-08-04T12:28:15.161996Z","finishedAt":"2022-08-04T12:28:15.163188Z"}
+```
+
+If Meilisearch has batched multiple tasks, it will only trigger the webhook once all tasks in a batch are finished. In this case, the response payload will include all tasks, each separated by a new line:
+
+```ndjson
+{"uid":4,"indexUid":"books","status":"succeeded","type":"documentAdditionOrUpdate","canceledBy":null,"details.receivedDocuments":1,"details.indexedDocuments":1,"duration":"PT0.001192S","enqueuedAt":"2022-08-04T12:28:15.159167Z","startedAt":"2022-08-04T12:28:15.161996Z","finishedAt":"2022-08-04T12:28:15.163188Z"}
+{"uid":5,"indexUid":"books","status":"succeeded","type":"documentAdditionOrUpdate","canceledBy":null,"details.receivedDocuments":1,"details.indexedDocuments":1,"duration":"PT0.001192S","enqueuedAt":"2022-08-04T12:28:15.159167Z","startedAt":"2022-08-04T12:28:15.161996Z","finishedAt":"2022-08-04T12:28:15.163188Z"}
+{"uid":6,"indexUid":"books","status":"succeeded","type":"documentAdditionOrUpdate","canceledBy":null,"details.receivedDocuments":1,"details.indexedDocuments":1,"duration":"PT0.001192S","enqueuedAt":"2022-08-04T12:28:15.159167Z","startedAt":"2022-08-04T12:28:15.161996Z","finishedAt":"2022-08-04T12:28:15.163188Z"}
+```
diff --git a/learn/configuration/instance_options.mdx b/learn/configuration/instance_options.mdx
index f1500f2e4e..19efac8551 100644
--- a/learn/configuration/instance_options.mdx
+++ b/learn/configuration/instance_options.mdx
@@ -425,7 +425,7 @@ This command will throw an error if `--import-snapshot` is not defined.
 
 Notifies the configured URL whenever Meilisearch [finishes processing a task](/learn/async/asynchronous_operations#task-status) or batch of tasks. Meilisearch uses the URL as given, retaining any specified query parameters.
 
-The webhook payload contains the list of finished tasks in [ndjson](https://ndjson.org/).
+The webhook payload contains the list of finished tasks in [ndjson](https://github.com/ndjson/ndjson-spec). For more information, [consult the dedicated task webhook guide](/learn/async/task_webhook).
 
 ### Task webhook authorization header