Skip to main content
Webhooks let Mixpeek notify your systems when events occur in real time. Use them to trigger workflows, invalidate caches, and keep downstream systems in sync without polling.

​
What are webhooks?

  • Outbound notifications: Mixpeek sends HTTP POST requests to your endpoints when events occur
  • Low latency: Receive changes in near real time to kick off downstream jobs
  • Channel-flexible: Deliver to URLs (webhook), Slack, Email, or SMS via channel configs
  • Cache-aware: Events include cache invalidation scopes for maintaining consistency

​
Event types

Events are grouped into categories based on the resources they track:
  • Object Lifecycle
  • Collection Lifecycle
  • Taxonomy Lifecycle
  • Cluster Lifecycle
  • object.created ✅ - New object ingested into bucket
  • object.updated ✅ - Object content or metadata updated
  • object.deleted ✅ - Object permanently deleted
  • object.redacted ⏳ - PII stripped from object (planned)
Status Legend: ✅ Currently implemented | ⏳ Planned for future release

​
Channels

Webhook (HTTP)

POST to your HTTPS endpoint with optional custom headers and a JSON body

Slack

Notify a Slack channel via a webhook URL and template

Email

Send email notifications with a subject/body template

SMS

Short text alerts for critical events

​
Delivery model

  • Request: For webhook channel, Mixpeek issues an HTTP POST to your configured url
  • Headers: Optional custom headers are included (e.g., shared secret)
  • Timeout: Delivery attempts honor a configurable request timeout (default 10s)
  • Payload: JSON body, optionally rendered from a Jinja2 payload_template
  • Success: Any 2xx response code is treated as success
Keep webhook endpoints idempotent and return quickly (e.g., enqueue work and respond 200). Long processing should happen asynchronously in your system.

​
Create a webhook

Use the API to register a webhook with one or more channels and event types: 
curl -X POST "https://api.mixpeek.com/v1/organizations/webhooks/" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "webhook_name": "prod-events",
        "event_types": ["object.created", "object.updated", "cluster.created"],
        "channels": [
          {
            "channel": "webhook",
            "configs": {
              "url": "https://example.com/hooks/mixpeek",
              "headers": { "X-Mixpeek-Secret": "${WEBHOOK_SECRET}" },
              "timeout": 10
            }
          }
        ]
      }'

​
Standard payload structure

All webhook events follow a consistent structure: 
{
  "event_id": "evt_abc123",
  "event_type": "object.created",
  "occurred_at": "2025-10-08T16:09:00Z",
  "namespace": "acme",
  "collection": "articles",
  "actor": "system",
  "subject": {
    "type": "object",
    "id": "obj_abc123"
  },
  "version": "v1",
  "index_signature": "sig_c1f9...",
  "cache_scope_to_invalidate": {
    "scope": "key",
    "keys": ["mixpeek:acme:articles:obj_abc123"]
  },
  "metadata": {
    "object_id": "obj_abc123",
    "bucket_id": "bkt_xyz",
    "namespace_id": "ns_acme",
    "content_type": "video/mp4"
  }
}

​
Cache invalidation scopes

Events include cache invalidation information to help maintain consistency:
ScopeWhen UsedExample
KEYDocument-level changes (create, update, delete)Single object modified
COLLECTIONCollection-wide changes (config, taxonomy, ranker)Collection settings updated
NAMESPACENamespace-wide changes (model rollout)Global model update
Use the cache_scope_to_invalidate field to intelligently invalidate caches in your application.

​
Receive webhooks (server examples)

  • Node (Express)
  • Python (Flask)
import express from "express";

const app = express();
app.use(express.json());

app.post("/hooks/mixpeek", (req, res) => {
  const signature = req.header("X-Mixpeek-Secret");
  // Verify shared secret or signature here

  const { event_type, event_id, data } = req.body;
  // Enqueue work and ack quickly
  res.sendStatus(200);
});

app.listen(3000);

​
Event-specific examples

  • Object Created
  • Collection Updated
  • Taxonomy Created
{
  "event_type": "object.created",
  "subject": { "type": "object", "id": "obj_abc123" },
  "metadata": {
    "object_id": "obj_abc123",
    "bucket_id": "bkt_xyz",
    "namespace_id": "ns_acme",
    "content_type": "video/mp4"
  },
  "cache_scope_to_invalidate": {
    "scope": "key",
    "keys": ["mixpeek:ns_acme:col_articles:obj_abc123"]
  }
}

​
Security & reliability

Verify origin

Use a shared secret in headers (e.g., X-Mixpeek-Secret) and verify on receipt

HTTPS only

Terminate TLS and reject plain HTTP endpoints

Idempotency

Deduplicate using event_id to safely handle retries

Fast acks

Respond 2xx quickly; do heavy work asynchronously

​
Best practices

Store event IDs

Persist event_id to deduplicate retries and track event history

Use cache scopes

Leverage cache_scope_to_invalidate to intelligently refresh your caches

Subscribe selectively

Only subscribe to event types your application needs to reduce noise

Monitor delivery

Track webhook delivery success rates and response times in your observability stack

​
Operate & monitor

  • Observability: Track delivery successes/failures in your logs/metrics; correlate by event_id
  • Alerting: Page on sustained non‑2xx rates from your webhook endpoints
  • Tasks: Prefer webhooks over tight polling; for long jobs, see Tasks
  • Testing: Use the E2E webhook test suite for comprehensive validation

​
Troubleshooting

1

401/403 responses

Ensure your endpoint accepts the request and validates the shared secret correctly
2

Timeouts

Keep processing under the configured timeout; otherwise quickly ack and process async
3

Unexpected payload

If using payload_template, validate your template; otherwise log the raw body for inspection
4

Missing events

Verify your webhook subscription includes the expected event_types and is is_active: true
5

Duplicate events

Events may be delivered multiple times on retry; always use event_id for deduplication

​
References

List Webhooks

View all webhook subscriptions for your organization

Create Webhook

Register a new webhook subscription

Get Webhook

Retrieve webhook details by ID

Update Webhook

Modify webhook configuration

Delete Webhook

Remove a webhook subscription

Tasks

Monitor asynchronous jobs that trigger webhook events

Observability

Health checks and monitoring for webhook delivery

Security

Authentication and authorization best practices
⌘I