Webhooks - Meilisearch Documentation

Capabilities

Full-text search

Hybrid and semantic search

Geo search

Conversational search

Multi-search

Filtering, sorting, and faceting

Personalization

Analytics

Security and tenant tokens

Search rules

Platform

Indexing

Webhooks let Meilisearch notify an external HTTP endpoint whenever a task completes. Use them to trigger downstream actions automatically, such as purging a cache after a successful index update or alerting your team when a task fails. Webhooks are configured per project in Project Settings > Webhooks. Up to 20 webhooks can be configured per project.

Webhooks section in Project Settings showing the Add webhook button and description

Adding a webhook

Go to Project Settings > Webhooks and click + Add webhook.

Add webhook modal with Webhook URL and Authorization Header fields

Enter the Webhook URL: the endpoint where Meilisearch will send POST requests with task data.
Optionally, enter an Authorization Header (for example, Bearer your-secret-token). This header is sent with every webhook request so your endpoint can verify the source.
Click Add webhook.

How webhooks work

When a task completes, Meilisearch sends an HTTP POST request to your configured URL. The request body is ndjson (newline-delimited JSON), with one task object per line matching the format returned by the Tasks API.

{"uid":1,"indexUid":"movies","status":"succeeded","type":"documentAdditionOrUpdate",...}
{"uid":2,"indexUid":"movies","status":"failed","type":"documentAdditionOrUpdate",...}

Your endpoint must respond with a 2xx status code. Non-2xx responses are treated as failures and retried with exponential backoff.

Multiple active webhooks may impact performance. Keep only the webhooks you actively use.

Securing your endpoint

Always validate the Authorization header on incoming webhook requests. Set a long random secret and reject requests that do not match.

app.post('/webhook', (req, res) => {
  if (req.headers['authorization'] !== process.env.WEBHOOK_SECRET) {
    return res.status(401).end();
  }
  // Process the ndjson payload
  res.status(200).end();
});

Example use cases

Use case	Description
Cache purge	Invalidate your CDN or application cache after a `documentAdditionOrUpdate` task succeeds
Slack notification	Send a message to a Slack channel when any task fails
CI/CD integration	Signal a deployment pipeline that a new index is ready
Audit log	Append every task event to an external log store for compliance

Overview Experimental features

​Adding a webhook

​How webhooks work

​Securing your endpoint

​Example use cases

Adding a webhook

How webhooks work

Securing your endpoint

Example use cases