Using task webhooks

This guide teaches you how to configure a single webhook via instance options to notify a URL when Meilisearch completes a task.

If you are using Meilisearch Cloud or need to configure multiple webhooks, use the /webhooks API route instead.

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:

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:

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:

curl \
  -X POST 'MEILISEARCH_URL/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 format:

{"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:

{"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"}

Getting started

AI-powered search

Conversational search

Personalization

Self-hosted

Analytics

Teams

Tasks and asynchronous operations

Configuration

Filtering and sorting

Security and permissions

Multi-search

Update and migration

Data backup

Indexing

Engine

Relevancy

Resources

Requirements

Configure the webhook URL

Optional: configure an authorization header

Test the webhook

​Requirements

​Configure the webhook URL

​Optional: configure an authorization header

​Test the webhook

Requirements

Configure the webhook URL

Optional: configure an authorization header

Test the webhook