Skip to main content
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 movies index: 
curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/documents' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    {
      "id": 287947,
      "title": "Shazam",
      "poster": "https://image.tmdb.org/t/p/w1280/xnopI5Xtky18MPhK40cZAGAOVeV.jpg",
      "overview": "A boy is given the ability to become an adult superhero in times of need with a single magic word.",
      "release_date": "2019-03-23"
    }
  ]'
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":"movies","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":"movies","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":"movies","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":"movies","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"}