From 4ec1f396bcc4cd8c8a20d1d3835c63ca2d0769d4 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 7 Aug 2025 18:58:58 +0200 Subject: [PATCH 01/10] add webhooks reference --- .code-samples.meilisearch.yaml | 26 +++++++ docs.json | 3 +- reference/api/webhooks.mdx | 137 +++++++++++++++++++++++++++++++++ 3 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 reference/api/webhooks.mdx diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index c117f564cb..0f0a28bb67 100644 --- a/.code-samples.meilisearch.yaml +++ b/.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: |- diff --git a/docs.json b/docs.json index e2ae21d7b7..45a1c86022 100644 --- a/docs.json +++ b/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" ] }, { diff --git a/reference/api/webhooks.mdx b/reference/api/webhooks.mdx new file mode 100644 index 0000000000..f34767ca73 --- /dev/null +++ b/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 + + + +Get a list of all webhooks configured in the current Meilisearch instance. + +### Example + + + +#### 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 + + + +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 + + + +#### 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 + + + +Update the configuration for the specified webhook. To remove a field, set its value to `null`. + + +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`. + + +### Example + + + +#### Response: `200 OK` + +```json +{ + "uuid": "627ea538-733d-4545-8d2d-03526eb381ce", + "url": "WEBHOOK_TARGET_URL", + "headers": { + "authorization": "SECURITY_KEY" + }, + "isEditable": true +} +``` + +## Delete webhook + + + +Delete a webhook and stop sending task completion data to the target URL. + + +It is not possible to delete webhooks whose `isEditable` field is set to `false`. + + +### Example + + + +#### Response: `204 No Content` From 8df23c1bdb33e6a346eda12094861c39c85afe84 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 7 Aug 2025 19:21:31 +0200 Subject: [PATCH 02/10] add links and error codes --- learn/async/asynchronous_operations.mdx | 2 +- learn/async/task_webhook.mdx | 6 +++- learn/async/working_with_tasks.mdx | 2 +- .../configure_meilisearch_at_launch.mdx | 2 ++ reference/errors/error_codes.mdx | 32 +++++++++++++++++++ 5 files changed, 41 insertions(+), 3 deletions(-) diff --git a/learn/async/asynchronous_operations.mdx b/learn/async/asynchronous_operations.mdx index 0c3816fec1..db550fabc1 100644 --- a/learn/async/asynchronous_operations.mdx +++ b/learn/async/asynchronous_operations.mdx @@ -83,7 +83,7 @@ Tasks always contain a field indicating the task's current `status`. This field - **`failed`**: a failure occurred when processing the task. No changes were made to the database - **`canceled`**: the task was canceled -`succeeded`, `failed`, and `canceled` tasks are finished tasks. Meilisearch keeps them in the task database but has finished processing these tasks. It is possible to [configure a webhook](/learn/self_hosted/configure_meilisearch_at_launch#task-webhook-url) to notify external services when a task is finished. +`succeeded`, `failed`, and `canceled` tasks are finished tasks. Meilisearch keeps them in the task database but has finished processing these tasks. It is possible to [configure a webhook](/reference/api/webhooks) to notify external services when a task is finished. `enqueued` and `processing` tasks are unfinished tasks. Meilisearch is either processing them or will do so in the future. diff --git a/learn/async/task_webhook.mdx b/learn/async/task_webhook.mdx index b671c0528e..5516e7c043 100644 --- a/learn/async/task_webhook.mdx +++ b/learn/async/task_webhook.mdx @@ -5,7 +5,11 @@ description: Learn how to use webhooks to react to changes in your Meilisearch d sidebarDepth: 3 --- -This guide teaches you how to use webhooks to notify a URL when Meilisearch completed a [task](/learn/async/asynchronous_operations). +This guide teaches you how to configure a single webhook via instance options to notify a URL when Meilisearch completes a [task](/learn/async/asynchronous_operations). + + +If you are using Meilisearch Cloud or need to configure multiple webhooks, use the [`/webhooks` API route](/reference/api/webhooks) instead. + ## Requirements diff --git a/learn/async/working_with_tasks.mdx b/learn/async/working_with_tasks.mdx index 3127b3860d..fb4d3d45e8 100644 --- a/learn/async/working_with_tasks.mdx +++ b/learn/async/working_with_tasks.mdx @@ -86,7 +86,7 @@ This will return the full task object: } ``` -If the task is still `enqueued` or `processing`, wait a few moments and query the database once again. If you are working with a self-hosted Meilisearch instance, you may also [set up a webhook listener](/learn/async/task_webhook). +If the task is still `enqueued` or `processing`, wait a few moments and query the database once again. You may also [set up a webhook listener](/reference/api/webhooks). When `status` changes to `succeeded`, Meilisearch has finished processing your request. diff --git a/learn/self_hosted/configure_meilisearch_at_launch.mdx b/learn/self_hosted/configure_meilisearch_at_launch.mdx index 5bd0c3dc10..138daddce0 100644 --- a/learn/self_hosted/configure_meilisearch_at_launch.mdx +++ b/learn/self_hosted/configure_meilisearch_at_launch.mdx @@ -495,6 +495,8 @@ Notifies the configured URL whenever Meilisearch [finishes processing a task](/l 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). +The task webhook option is only available for self-hosted instances. If you are using Meilisearch Cloud, use the [`/webhooks` API route](/reference/api/webhooks) instead. + ### Task webhook authorization header **Environment variable**: `MEILI_TASK_WEBHOOK_AUTHORIZATION_HEADER`
diff --git a/reference/errors/error_codes.mdx b/reference/errors/error_codes.mdx index 48c5448d59..e696bfc40c 100644 --- a/reference/errors/error_codes.mdx +++ b/reference/errors/error_codes.mdx @@ -82,6 +82,18 @@ The [`uid`](/reference/api/indexes#index-object) field of an index cannot be mod The [`updatedAt`](/reference/api/indexes#index-object) field of an index cannot be modified. +### `immutable_webhook` + +You tried to modify a reserved [webhook](/reference/api/webhooks). Reserved webhooks are configured by Meilisearch Cloud and have `isEditable` set to `true`. Webhooks created with an instance option are also ummutable. + +### `immutable_webhook_uuid` + +You tried to manually set a webhook `uuid`. Meilisearch automatically generates `uuid` for webhooks. + +### `immutable_webhook_is_editable` + +You tried to manually set a webhook's `isEditable` field. Meilisearch automatically sets `isEditable` for all webhooks. Only reserved webhooks have `isEditable` set to `false`. + ## `index_already_exists` An index with this [`uid`](/reference/api/indexes#index-object) already exists, check out our guide on [index creation](/learn/getting_started/indexes). @@ -595,6 +607,22 @@ The requested task type is invalid. Please use one of the [possible values](/ref The [`uids`](/reference/api/tasks#query-parameters) query parameter is invalid. +### `invalid_webhooks` + +The create webhook request did not contain a valid JSON payload. Meilisearch also returns this error when you try to create more than 20 webhooks. + +### `invalid_webhook_url` + +The provided webhook URL isn’t a valid JSON value, `null`, or missing. + +### `invalid_webhook_headers` + +The provided webhook `headers` field is not a JSON object or not a valid HTTP header. Meilisearch also returns this error if you set more than 200 header fields for a single webhook. + +### `invalid_webhook_uuid` + +The provided webhook `uuid` is not a valid uuid v4 value. + ## `io_error` This error generally occurs when the host system has no space left on the device or when the database doesn't have read or write access. @@ -726,3 +754,7 @@ The remote instance answered with `500 INTERNAL ERROR`. ### `remote_timeout` The proxy did not answer in the allocated time. + +### `webhook_not_found` + +The provided webhook `uuid` does not correspond to any configured webhooks in the instance. From 702be3c8073b8471b68d7392ee97c4984420137d Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 11 Aug 2025 17:24:55 +0200 Subject: [PATCH 03/10] add new endpoint, key permissions --- .code-samples.meilisearch.yaml | 3 +++ reference/api/keys.mdx | 4 ++++ reference/api/webhooks.mdx | 31 +++++++++++++++++++++++++++---- 3 files changed, 34 insertions(+), 4 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 0f0a28bb67..ca8c958334 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1482,6 +1482,9 @@ export_post_1: |- webhooks_get_1: |- curl \ -X GET 'MEILISEARCH_URL/webhooks' +webhooks_get_single_1: |- + curl \ + -X GET 'MEILISEARCH_URL/webhooks/WEBHOOK_UUID' webhooks_post_1: |- curl \ -X POST 'MEILISEARCH_URL/webhooks' \ diff --git a/reference/api/keys.mdx b/reference/api/keys.mdx index e3cd2bf3a6..f6b71c801b 100644 --- a/reference/api/keys.mdx +++ b/reference/api/keys.mdx @@ -111,6 +111,10 @@ For security reasons, we do not recommend creating keys that can perform all act | **`network.get`** | Provides access to the [get the network object](/reference/api/network#get-the-network-object) endpoint | | **`network.update`** | Provides access to the [update the network object](/reference/api/network#update-the-network-object) endpoint | | **`chatCompletions`** | Provides access to the [chat completions endpoints](/reference/api/chats). Requires experimental feature to be enabled | +| **`webhooks.get`** | Provides access to the [get webhooks](/reference/api/webhooks#get-all-webhooks) endpoints | +| **`webhooks.create`** | Provides access to the [create webhooks](/reference/api/webhooks#create-a-webhook) endpoint | +| **`webhooks.update`** | Provides access to the [update webhooks](/reference/api/webhooks#update-a-webhook) endpoint | +| **`webhooks.delete`** | Provides access to the [delete webhooks](/reference/api/webhooks#delete-a-webhook) endpoint | ### `indexes` diff --git a/reference/api/webhooks.mdx b/reference/api/webhooks.mdx index f34767ca73..21a5f1cf72 100644 --- a/reference/api/webhooks.mdx +++ b/reference/api/webhooks.mdx @@ -36,7 +36,7 @@ When Meilisearch finishes processing a task, it sends the relevant [task object] ## Get all webhooks - + Get a list of all webhooks configured in the current Meilisearch instance. @@ -67,7 +67,30 @@ Get a list of all webhooks configured in the current Meilisearch instance. } ``` -## Create new webhook +## Get a single webhook + + + +Get a single webhook configured in the current Meilisearch instance. + +### Example + + + +#### Response: `200 OK` + +```json +{ + "uuid": "UUID_V4", + "url": "WEBHOOK_TARGET_URL", + "headers": { + "HEADER": "VALUE", + }, + "isEditable": false +} +``` + +## Create a webhook @@ -91,7 +114,7 @@ Create a new webhook. When Meilisearch finishes processing a task, it sends the } ``` -## Update webhook +## Update a webhook @@ -120,7 +143,7 @@ Meilisearch Cloud may create internal webhooks to support features such as Analy } ``` -## Delete webhook +## Delete a webhook From d3b5fba9abb2f7a1be75c8db929b11711182773b Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 11 Aug 2025 18:13:01 +0200 Subject: [PATCH 04/10] update postman collection --- .../misc/meilisearch-collection-postman.json | 135 +++++++++++++++++- 1 file changed, 133 insertions(+), 2 deletions(-) diff --git a/assets/misc/meilisearch-collection-postman.json b/assets/misc/meilisearch-collection-postman.json index dcf5fa6949..ac4ef3a743 100644 --- a/assets/misc/meilisearch-collection-postman.json +++ b/assets/misc/meilisearch-collection-postman.json @@ -1,7 +1,7 @@ { "info": { - "_postman_id": "f4b62ec3-0403-44ba-b6f4-640badbbd1b2", - "name": "Meilisearch v1.16", + "_postman_id": "a0638dc7-4c40-4c37-822d-bf342771238d", + "name": "Meilisearch latest", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "25294324" }, @@ -3044,6 +3044,137 @@ } ] }, + { + "name": "Webhooks", + "item": [ + { + "name": "Get all webhooks", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{url}}/webhooks", + "host": [ + "{{url}}" + ], + "path": [ + "webhooks" + ], + "query": [ + { + "key": "offset", + "value": "0", + "disabled": true + }, + { + "key": "limit", + "value": "10", + "disabled": true + } + ] + } + }, + "response": [] + }, + { + "name": "Get one webhook", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{url}}/webhooks/WEBHOOK_UUID", + "host": [ + "{{url}}" + ], + "path": [ + "webhooks", + "WEBHOOK_UUID" + ] + } + }, + "response": [] + }, + { + "name": "Create a webhook", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"name\": \"docs-key\",\n \"description\": \"Key to add and delete documents, in `books` index.\",\n \"actions\": [\n \"documents.add\",\n \"documents.delete\" \n ],\n \"indexes\": [\n \"books\"\n ],\n \"expiresAt\": null\n}" + }, + "url": { + "raw": "{{url}}/webhooks", + "host": [ + "{{url}}" + ], + "path": [ + "webhooks" + ] + } + }, + "response": [] + }, + { + "name": "Update a webhook", + "request": { + "method": "PATCH", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"description\": \"Key to add and delete documents, but also to create indexes, in `book` index.\"\n}" + }, + "url": { + "raw": "{{url}}/webhooks/WEBHOOK_UUID", + "host": [ + "{{url}}" + ], + "path": [ + "webhooks", + "WEBHOOK_UUID" + ] + } + }, + "response": [] + }, + { + "name": "Delete a webhook", + "request": { + "method": "DELETE", + "header": [ + { + "key": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "url": { + "raw": "{{url}}/webhooks/WEBHOOK_UUID", + "host": [ + "{{url}}" + ], + "path": [ + "webhooks", + "WEBHOOK_UUID" + ] + } + }, + "response": [] + } + ] + }, { "name": "Stats", "item": [ From d6f0fb7c23bd4f554cb8dcc1a8e5dca73efd10cf Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 11 Aug 2025 16:13:26 +0000 Subject: [PATCH 05/10] Update code samples [skip ci] --- snippets/samples/code_samples_export_1.mdx | 10 ++++++++++ snippets/samples/code_samples_export_2.mdx | 16 ++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 snippets/samples/code_samples_export_1.mdx create mode 100644 snippets/samples/code_samples_export_2.mdx diff --git a/snippets/samples/code_samples_export_1.mdx b/snippets/samples/code_samples_export_1.mdx new file mode 100644 index 0000000000..c265724517 --- /dev/null +++ b/snippets/samples/code_samples_export_1.mdx @@ -0,0 +1,10 @@ + + +```go Go +client.Export(&meilisearch.ExportParams{ + URL: URL, + APIKey: API_KEY, + PayloadSize: "100MB", +}); +``` + \ No newline at end of file diff --git a/snippets/samples/code_samples_export_2.mdx b/snippets/samples/code_samples_export_2.mdx new file mode 100644 index 0000000000..c68e40ba5d --- /dev/null +++ b/snippets/samples/code_samples_export_2.mdx @@ -0,0 +1,16 @@ + + +```go Go +client.Export(&meilisearch.ExportParams{ + URL: URL, + APIKey: API_KEY, + PayloadSize: "50MB", + Indexes: map[string]meilisearch.IndexExportOptions{ + indexUID: { + Filter: filter, + OverrideSettings: true, + } + } +}); +``` + \ No newline at end of file From 35de3cee48f3da9ae529cf622bfec537271e46cb Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 12 Aug 2025 17:55:54 +0200 Subject: [PATCH 06/10] Apply suggestions from code review Co-authored-by: Mubelotix --- .code-samples.meilisearch.yaml | 2 +- learn/self_hosted/configure_meilisearch_at_launch.mdx | 2 +- reference/errors/error_codes.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index ca8c958334..484681fc41 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1507,7 +1507,7 @@ webhooks_patch_1: |- }' webhooks_delete_1: |- curl \ - -X DELETE 'MEILISEARCH_URL/webhooks' + -X DELETE 'MEILISEARCH_URL/webhooks/WEBHOOK_UUID' ### Code samples for experimental features experimental_get_metrics_1: |- diff --git a/learn/self_hosted/configure_meilisearch_at_launch.mdx b/learn/self_hosted/configure_meilisearch_at_launch.mdx index 138daddce0..531e9a12b5 100644 --- a/learn/self_hosted/configure_meilisearch_at_launch.mdx +++ b/learn/self_hosted/configure_meilisearch_at_launch.mdx @@ -495,7 +495,7 @@ Notifies the configured URL whenever Meilisearch [finishes processing a task](/l 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). -The task webhook option is only available for self-hosted instances. If you are using Meilisearch Cloud, use the [`/webhooks` API route](/reference/api/webhooks) instead. +The task webhook option requires having access to a command-line interface. If you are using Meilisearch Cloud, use the [`/webhooks` API route](/reference/api/webhooks) instead. ### Task webhook authorization header diff --git a/reference/errors/error_codes.mdx b/reference/errors/error_codes.mdx index e696bfc40c..e72b97995d 100644 --- a/reference/errors/error_codes.mdx +++ b/reference/errors/error_codes.mdx @@ -613,7 +613,7 @@ The create webhook request did not contain a valid JSON payload. Meilisearch als ### `invalid_webhook_url` -The provided webhook URL isn’t a valid JSON value, `null`, or missing. +The provided webhook URL isn’t a valid JSON string, is `null`, is missing, or its value cannot be parsed as a valid URL. ### `invalid_webhook_headers` From ca10026b30dddd6b5795b4c97593be309731611c Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 12 Aug 2025 18:40:32 +0200 Subject: [PATCH 07/10] address reviewer feedback --- assets/misc/meilisearch-collection-postman.json | 4 ++-- reference/api/keys.mdx | 2 +- reference/api/webhooks.mdx | 4 +++- reference/errors/error_codes.mdx | 2 +- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/assets/misc/meilisearch-collection-postman.json b/assets/misc/meilisearch-collection-postman.json index ac4ef3a743..1058feab07 100644 --- a/assets/misc/meilisearch-collection-postman.json +++ b/assets/misc/meilisearch-collection-postman.json @@ -3107,7 +3107,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"name\": \"docs-key\",\n \"description\": \"Key to add and delete documents, in `books` index.\",\n \"actions\": [\n \"documents.add\",\n \"documents.delete\" \n ],\n \"indexes\": [\n \"books\"\n ],\n \"expiresAt\": null\n}" + "raw": "{\n \"url\": \"WEBHOOK_TARGET_URL\",\n \"headers\": {\n \"authorization\": \"SECURITY_KEY\",\n \"referer\": \"https://example.com\"\n }\n}" }, "url": { "raw": "{{url}}/webhooks", @@ -3134,7 +3134,7 @@ ], "body": { "mode": "raw", - "raw": "{\n \"description\": \"Key to add and delete documents, but also to create indexes, in `book` index.\"\n}" + "raw": "{\n \"header\": {\n \"referer\": null\n }\n}" }, "url": { "raw": "{{url}}/webhooks/WEBHOOK_UUID", diff --git a/reference/api/keys.mdx b/reference/api/keys.mdx index f6b71c801b..71bbf10958 100644 --- a/reference/api/keys.mdx +++ b/reference/api/keys.mdx @@ -78,7 +78,7 @@ Custom API keys are deterministic: `key` is a SHA256 hash of the `uid` and maste **Default value**: N/A
**Description**: An array of API actions permitted for the key, represented as strings. API actions are only possible on authorized [`indexes`](#indexes). `["*"]` for all actions. -You can use `*` as a wildcard to access all endpoints for the `documents`, `indexes`, `tasks`, `settings`, `stats` and `dumps` actions. For example, `documents.*` gives access to all document actions. +You can use `*` as a wildcard to access all endpoints for the `documents`, `indexes`, `tasks`, `settings`, `stats`, `webhooks`, and `dumps` actions. For example, `documents.*` gives access to all document actions. For security reasons, we do not recommend creating keys that can perform all actions. diff --git a/reference/api/webhooks.mdx b/reference/api/webhooks.mdx index 21a5f1cf72..5b41807cc7 100644 --- a/reference/api/webhooks.mdx +++ b/reference/api/webhooks.mdx @@ -28,7 +28,7 @@ Use the `/webhooks` to trigger automatic workflows when Meilisearch finishes pro - `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 +- `isEditable`: read-only Boolean field indicating whether you can edit the webhook. Meilisearch automatically sets this to `true` for all webhooks created via the API and to `false` for reserved webhooks ## The webhook payload @@ -96,6 +96,8 @@ Get a single webhook configured in the current Meilisearch instance. 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. +You can create up to 20 webhooks. Having multiple webhooks active at the same time may negatively impact performance. + ### Example diff --git a/reference/errors/error_codes.mdx b/reference/errors/error_codes.mdx index e72b97995d..41302bef65 100644 --- a/reference/errors/error_codes.mdx +++ b/reference/errors/error_codes.mdx @@ -84,7 +84,7 @@ The [`updatedAt`](/reference/api/indexes#index-object) field of an index cannot ### `immutable_webhook` -You tried to modify a reserved [webhook](/reference/api/webhooks). Reserved webhooks are configured by Meilisearch Cloud and have `isEditable` set to `true`. Webhooks created with an instance option are also ummutable. +You tried to modify a reserved [webhook](/reference/api/webhooks). Reserved webhooks are configured by Meilisearch Cloud and have `isEditable` set to `true`. Webhooks created with an instance option are also immutable. ### `immutable_webhook_uuid` From 4dc73db9a48142a6de4945244b810d44ae095aa3 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 13 Aug 2025 13:24:18 +0200 Subject: [PATCH 08/10] remove query params from GET /webhooks --- assets/misc/meilisearch-collection-postman.json | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/assets/misc/meilisearch-collection-postman.json b/assets/misc/meilisearch-collection-postman.json index 1058feab07..9025497085 100644 --- a/assets/misc/meilisearch-collection-postman.json +++ b/assets/misc/meilisearch-collection-postman.json @@ -3059,18 +3059,6 @@ ], "path": [ "webhooks" - ], - "query": [ - { - "key": "offset", - "value": "0", - "disabled": true - }, - { - "key": "limit", - "value": "10", - "disabled": true - } ] } }, From 4e201e5ea7b26150ca2ea9bfee381385c1744ff3 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 13 Aug 2025 11:24:53 +0000 Subject: [PATCH 09/10] Update code samples [skip ci] --- snippets/samples/code_samples_webhooks_delete_1.mdx | 6 ++++++ snippets/samples/code_samples_webhooks_get_1.mdx | 6 ++++++ .../samples/code_samples_webhooks_get_single_1.mdx | 6 ++++++ snippets/samples/code_samples_webhooks_patch_1.mdx | 10 ++++++++++ snippets/samples/code_samples_webhooks_post_1.mdx | 12 ++++++++++++ 5 files changed, 40 insertions(+) create mode 100644 snippets/samples/code_samples_webhooks_delete_1.mdx create mode 100644 snippets/samples/code_samples_webhooks_get_1.mdx create mode 100644 snippets/samples/code_samples_webhooks_get_single_1.mdx create mode 100644 snippets/samples/code_samples_webhooks_patch_1.mdx create mode 100644 snippets/samples/code_samples_webhooks_post_1.mdx diff --git a/snippets/samples/code_samples_webhooks_delete_1.mdx b/snippets/samples/code_samples_webhooks_delete_1.mdx new file mode 100644 index 0000000000..9c59ccabec --- /dev/null +++ b/snippets/samples/code_samples_webhooks_delete_1.mdx @@ -0,0 +1,6 @@ + + +```javascript JS +client.deleteWebhook(WEBHOOK_UUID) +``` + \ No newline at end of file diff --git a/snippets/samples/code_samples_webhooks_get_1.mdx b/snippets/samples/code_samples_webhooks_get_1.mdx new file mode 100644 index 0000000000..fb178ca848 --- /dev/null +++ b/snippets/samples/code_samples_webhooks_get_1.mdx @@ -0,0 +1,6 @@ + + +```javascript JS +client.getWebhooks() +``` + \ No newline at end of file diff --git a/snippets/samples/code_samples_webhooks_get_single_1.mdx b/snippets/samples/code_samples_webhooks_get_single_1.mdx new file mode 100644 index 0000000000..a474f9b417 --- /dev/null +++ b/snippets/samples/code_samples_webhooks_get_single_1.mdx @@ -0,0 +1,6 @@ + + +```javascript JS +client.getWebhook(WEBHOOK_UUID) +``` + \ No newline at end of file diff --git a/snippets/samples/code_samples_webhooks_patch_1.mdx b/snippets/samples/code_samples_webhooks_patch_1.mdx new file mode 100644 index 0000000000..7c1db65856 --- /dev/null +++ b/snippets/samples/code_samples_webhooks_patch_1.mdx @@ -0,0 +1,10 @@ + + +```javascript JS +client.updateWebhook(WEBHOOK_UUID, { + headers: { + referer: null + } +}) +``` + \ No newline at end of file diff --git a/snippets/samples/code_samples_webhooks_post_1.mdx b/snippets/samples/code_samples_webhooks_post_1.mdx new file mode 100644 index 0000000000..cea90ce05e --- /dev/null +++ b/snippets/samples/code_samples_webhooks_post_1.mdx @@ -0,0 +1,12 @@ + + +```javascript JS +client.createWebhook({ + url: 'WEBHOOK_TARGET_URL', + headers: { + authorization: 'SECURITY_KEY', + referer: 'https://example.com' + } +}) +``` + \ No newline at end of file From d9c41246b18166ab794bde52815b235927f22a08 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 13 Aug 2025 16:18:01 +0200 Subject: [PATCH 10/10] add telemetry info --- learn/resources/telemetry.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/learn/resources/telemetry.mdx b/learn/resources/telemetry.mdx index 93674e8e9d..a778873a83 100644 --- a/learn/resources/telemetry.mdx +++ b/learn/resources/telemetry.mdx @@ -273,3 +273,5 @@ This list is liable to change with every new version of Meilisearch. It's not be | `export.avg_index_patterns` | Average number of index patterns set per export | `3.2` | `export.avg_patterns_with_filter` | Average number of index patterns with filters per export | `1.7` | `export.avg_payload_size` | Average payload size per export | `512` +| `webhooks_created` | Number of webhooks created in an instance | `2` +| `webhooks.updated` | Number of times all webhooks in an instance have been updated | `5`