This guide teaches you how to use webhooks to notify a URL when Meilisearch completed a task.

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

Was this page helpful?