Skip to main content
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

EventTriggerPayload Highlights
collection.documents.writtenEngine finishes writing documents to MVScollection_id, document_ids, index_signature
object.createdObject registered in a bucketbucket_id, object_id, metadata snapshot
batch.completedBatch processing succeededbatch_id, collection_ids, counts
cluster.completedClustering run finishedcluster_id, run_id, artifact URIs
taxonomy.materializedTaxonomy enrichment completedtaxonomy_id, collection_id, updated_document_count
Use /api-reference/webhooks/list-webhooks to see the full catalog.

​
Create a Webhook

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

{
  "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:
ProviderEndpointEvents handledUse case
MuxPOST /v1/webhooks/mux/{connection_id}video.asset.deleted, video.asset.updatedCascade-delete bucket objects when a Mux asset is deleted. Re-evaluate metadata filters when asset metadata changes. See Mux integration → Webhooks.
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