> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Respond to Mixpeek events without polling

Webhooks notify your systems when ingestion, enrichment, or retrieval events occur. The Engine writes events to MongoDB, Celery Beat dispatches them, and Mixpeek delivers HTTP POST requests (or channel-specific messages) until acknowledged.

## Event Flow

```
Engine → MongoDB (webhook_events) → Celery Beat → Celery Worker → HTTP POST → Your endpoint
```

* Events persist until the worker receives a 2xx response.
* Retries use exponential backoff; failures remain in MongoDB for inspection.
* Delivery includes cache scopes so you can invalidate selectively.

## Common Event Types

| Event                          | Trigger                                                             | Payload Highlights                                       |
| ------------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------- |
| `collection.documents.written` | Engine finishes writing documents to [MVS](https://mixpeek.com/mvs) | `collection_id`, `document_ids`, `index_signature`       |
| `object.created`               | Object registered in a bucket                                       | `bucket_id`, `object_id`, metadata snapshot              |
| `batch.completed`              | Batch processing succeeded                                          | `batch_id`, `collection_ids`, counts                     |
| `cluster.completed`            | Clustering run finished                                             | `cluster_id`, `run_id`, artifact URIs                    |
| `taxonomy.materialized`        | Taxonomy enrichment completed                                       | `taxonomy_id`, `collection_id`, `updated_document_count` |

Use `/api-reference/webhooks/list-webhooks` to see the full catalog.

## Create a Webhook

```bash theme={null}
curl -sS -X POST "$MP_API_URL/v1/organizations/webhooks" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_name": "prod-notifications",
    "event_types": [
      "collection.documents.written",
      "cluster.completed"
    ],
    "channels": [
      {
        "channel": "webhook",
        "configs": {
          "url": "https://hooks.example.com/mixpeek",
          "headers": { "X-Mixpeek-Secret": "super-secret"},
          "timeout": 10
        }
      }
    ]
  }'
```

Mixpeek also supports Slack, email, and SMS channels via channel-specific configs.

## Payload Structure

```json theme={null}
{
  "event_id": "evt_123",
  "event_type": "collection.documents.written",
  "occurred_at": "2025-10-28T10:03:22Z",
  "namespace_id": "ns_prod",
  "subject": {
    "type": "collection",
    "id": "col_products"
  },
  "metadata": {
    "document_count": 100,
    "collection_id": "col_products",
    "index_signature": "sig_xyz789"
  },
  "cache_scope": {
    "scope": "collection",
    "collection_id": "col_products"
  }
}
```

Use `event_id` for deduplication and store payloads for auditing.

## Security & Reliability

* Require HTTPS endpoints; reject plaintext URLs.
* Include a shared secret header (`X-Mixpeek-Secret`) and verify before processing.
* Respond quickly (\<10s). Offload heavy work to background jobs and return `200`.
* Use idempotent handlers; Mixpeek may retry on failure or timeout.
* Monitor webhook delivery with your logging pipeline; correlate by `event_id`.

## Operational Tips

1. Subscribe only to the events you need to reduce noise.
2. Combine webhook notifications with the Tasks API for full status context.
3. Use cache scopes to invalidate retriever caches efficiently (`collection`, `namespace`, or `key`).
4. Store webhook definitions in infrastructure-as-code so environments stay consistent.
5. Alert on sustained non-2xx responses—Mixpeek will keep retrying, but you should fix endpoint issues quickly.

## Inbound Webhooks (from upstream providers)

In addition to **outbound** webhooks (Mixpeek → your endpoint), Mixpeek can receive **inbound** webhooks from external systems to trigger ingestion and lifecycle events.

### Sync lifecycle webhooks

Some sync integrations support inbound webhooks for **lifecycle events** (delete, update) on previously synced assets:

| Provider | Endpoint                                | Events handled                               | Use case                                                                                                                                                                                                            |
| -------- | --------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mux**  | `POST /v1/webhooks/mux/{connection_id}` | `video.asset.deleted`, `video.asset.updated` | Cascade-delete bucket objects when a Mux asset is deleted. Re-evaluate metadata filters when asset metadata changes. See [Mux integration → Webhooks](/integrations/object-storage/mux#webhooks-delete-and-update). |

These webhooks share common properties:

* Scoped to a single connection by URL path (no Authorization header needed).
* Signatures verified with `hmac.compare_digest` and provider-specific HMAC schemes.
* Unhandled events acknowledged with `200` and `handled: false` so retries stop cleanly.

## References

* [Create Webhook](/api-reference/webhooks/create-webhook)
* [List Webhooks](/api-reference/webhooks/list-webhooks)
* [Delete Webhook](/api-reference/webhooks/delete-webhook)
* [Mux cascade-delete webhook](/integrations/object-storage/mux#cascade-delete-via-webhooks)
* [Tasks](/processing/tasks) – track the jobs that trigger webhook events
* [Security](/operations/security) – authentication, tenancy, and secret management