Webhooks

​

Event Flow

Engine → MongoDB (webhook_events) → work scheduler → delivery task → 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

​

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.execution.completed"
    ],
    "channels": [
      {
        "channel": "webhook",
        "configs": {
          "url": "https://hooks.example.com/mixpeek",
          "headers": { "X-Mixpeek-Secret": "super-secret"},
          "signing_secret": "a-long-random-string",
          "timeout": 10
        }
      }
    ]
  }'

​

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"
  }
}

​

Security & Reliability

• Require HTTPS endpoints; reject plaintext URLs.
• Every delivery names its event in two headers: X-Mixpeek-Event (the event type, such as alert.triggered) and X-Mixpeek-Event-Id (the event’s id, the same on a retry, so you can drop duplicates). The body is the event payload. A header you set on the webhook with the same name replaces ours.
• Set signing_secret and verify the X-Mixpeek-Signature header on every delivery (below). A static header such as X-Mixpeek-Secret also works, but it can be replayed.
• 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.

​

Verify a delivery

X-Mixpeek-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance_s: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, sig = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance_s:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

​

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 and fix the endpoint quickly. After 30 failed deliveries in a row spanning at least two hours, Mixpeek pauses the webhook (is_active: false, with paused_reason) and alerts your organization; any successful delivery resets the count. Update the webhook to turn it back on.
6. Use a real endpoint. Create and update refuse URLs whose host can never receive a delivery, such as example.com and .test or .invalid names.

​

Inbound Webhooks (from upstream providers)

​

Sync lifecycle webhooks

• 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
• List Webhooks
• Delete Webhook
• Mux cascade-delete webhook
• Tasks – track the jobs that trigger webhook events
• Security – authentication, tenancy, and secret management