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

🚩 To be able to configure a webhook to notify internal services (such as localhost), you will need to allow requests on private networks. 🚩
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 and allow requests on private networks

Depending on your setup, you may need to provide an authorization header and allow requests on private networks. Provide these using task-webhook-authorization-header and experimental-allowed-ip-networks: 
meilisearch \
  --task-webhook-url http://localhost:8000 \
  --task-webhook-authorization-header Bearer aSampleMasterKey \
  --experimental-allowed-ip-networks 127.0.0.0/8

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