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.
Adding a webhook
- Go to Project Settings > Webhooks and click + Add webhook.
- Enter the Webhook URL: the endpoint where Meilisearch will send POST requests with task data.
- Optionally, enter an Authorization Header (e.g.
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",...}
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 |
