Create Webhook

Create a new webhook for the user’s organization.

POST /v1/organizations/webhooks

Create Webhook

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/organizations/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channels": [
    {
      "channel": "slack",
      "configs": {
        "channel": "#alerts",
        "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX"
      }
    }
  ],
  "created_at": "2025-01-01T00:00:00Z",
  "description": "Slack notifications for object lifecycle",
  "event_types": [
    "object.created",
    "object.updated",
    "object.deleted"
  ],
  "is_active": true,
  "updated_at": "2025-01-01T00:00:00Z",
  "webhook_id": "wh_abc123def4567890",
  "webhook_name": "Engineering Slack Alerts"
}
'

200

{
  "channels": [
    {
      "channel": "slack",
      "configs": {
        "channel": "#alerts",
        "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX"
      }
    }
  ],
  "created_at": "2025-01-01T00:00:00Z",
  "description": "Slack notifications for object lifecycle",
  "event_types": [
    "object.created",
    "object.updated",
    "object.deleted"
  ],
  "is_active": true,
  "updated_at": "2025-01-01T00:00:00Z",
  "webhook_id": "wh_abc123def4567890",
  "webhook_name": "Engineering Slack Alerts"
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Configured webhook subscription for organization event notifications.

Webhooks enable real-time notifications when events occur in the system. Each webhook subscribes to specific event types and delivers notifications via one or more configured channels (Slack, email, HTTP).

Webhook Lifecycle: 1. Created with event_types and channels configured 2. is_active=True enables notification delivery 3. Events matching event_types trigger notifications to all channels 4. is_active=False temporarily pauses notifications without deletion 5. Webhook can be updated to add/remove event types or channels 6. Permanent deletion removes the webhook configuration

Use Cases: - Integrate Mixpeek events with external systems via HTTP webhooks - Notify teams in Slack when ingestion jobs complete - Send email alerts when critical failures occur - Trigger automated workflows based on state changes - Maintain audit trails by forwarding events to SIEM systems

Best Practices: - Subscribe only to events you need (reduces noise) - Use descriptive webhook_name for identification - Configure multiple channels for critical events (redundancy) - Set is_active=False to temporarily disable without losing config - Monitor webhook delivery failures via last_error tracking

webhook_name · string · required

REQUIRED. Human-readable name for the webhook. Displayed in dashboards, logs, and notification metadata. Should describe the webhook's purpose or destination. Format: 1-200 characters.

Required string length: 1 - 200

Examples:

"Slack Engineering Alerts"

"External System Integration"

"Audit Trail Logger"

"Production Monitoring"

event_types · enum<string>[] · required

REQUIRED. List of event types that trigger this webhook. When any of these events occur, notifications are sent to all channels. Must contain at least one event type. Common patterns: - ['object.created', 'object.updated'] for object lifecycle tracking - ['cluster.execution.completed', 'cluster.execution.failed'] for job monitoring - ['*'] for all events (use cautiously, high volume)

Minimum array length: 1

Webhook event types for real-time notifications.

These events are emitted when significant state changes occur in the system. Webhooks subscribe to specific event types and receive notifications via configured channels (email, Slack, HTTP webhooks).

Event Naming Convention: {resource}.{action}[.{sub-resource}[.{sub-action}]]

Examples: - object.created: New object ingested - collection.documents.written: Documents indexed - cluster.execution.completed: Cluster job finished

Cache Invalidation Annotations: Each event type includes a comment indicating recommended cache invalidation scope: - [KEY] = Invalidate specific document/object keys - [COLLECTION] = Invalidate collection-level cache - [NAMESPACE] = Invalidate namespace-level cache

Event Categories: - Object Lifecycle: Events for individual objects (create, update, delete) - Collection Lifecycle: Events for collections (create, update, delete, documents written) - Cluster Lifecycle: Events for clusters (create, update, delete, execution status) - Trigger Lifecycle: Events for cluster triggers (create, update, fire, execution status) - Taxonomy Lifecycle: Events for taxonomies (create, update, delete)

Use Cases: - Real-time sync with external systems - Audit trail and compliance logging - Automated workflows triggered by state changes - Cache invalidation for distributed systems - Notifications to team members via Slack/email

Available options: object.created, objects.created.batch, object.updated, object.deleted, document.created, document.updated, document.deleted, documents.updated.batch, documents.deleted.batch, collection.created, collection.updated, collection.deleted, collection.documents.written, collection.documents.batch_completed, cluster.created, cluster.updated, cluster.deleted, cluster.execution.started, cluster.execution.completed, cluster.execution.failed, trigger.created, trigger.updated, trigger.deleted, trigger.paused, trigger.resumed, trigger.fired, trigger.execution.completed, trigger.execution.failed, taxonomy.created, taxonomy.updated, taxonomy.deleted, alert.created, alert.updated, alert.deleted, alert.triggered, alert.execution.completed, alert.execution.failed, annotation.created, annotation.updated, annotation.deleted, resource.executed, resource.execution_failed, manifest.apply.resource_state

Examples:

[
  "object.created",
  "object.updated",
  "object.deleted"
]

[
  "cluster.execution.completed",
  "cluster.execution.failed"
]

["collection.documents.written"]

channels · WebhookChannel · object[] · required

REQUIRED. List of notification channels for event delivery. When an event occurs, notifications are sent to ALL configured channels. Must contain at least one channel. Multiple channels provide redundancy and multi-audience delivery. Example: Send to both Slack (team) and email (manager) for critical events.

Minimum array length: 1

Show child attributes

webhook_id · string

Unique identifier for the webhook. Auto-generated with 'wh_' prefix followed by secure random token. Format: wh_{16-character hex}. Used for API operations and event tracking.

Pattern: ^wh_[a-fA-F0-9]{16}$

Examples:

"wh_abc123def4567890"

"wh_1234567890abcdef"

internal_id · string | null

Organization internal identifier for multi-tenancy scoping. All webhook operations are scoped to this organization. Excluded from API responses for security. Format: int_{24-character secure token}.

resource_types · string[] | null

OPTIONAL. Deliver only events whose resource_type is one of these, for example ['retriever', 'taxonomy']. Applies to every event type: for resource.executed and resource.execution_failed the resource_type is the primitive that ran (it travels in the payload); for the per-kind types it is the first segment of the event type. Omitted or empty: no resource_type filter.

Example:

["retriever"]

is_active · boolean · default: true

Whether the webhook is currently active and should send notifications. True: Events trigger notifications to channels. False: Webhook is paused, no notifications sent but config preserved. Use to temporarily disable webhooks without losing configuration. Default: True

delivery_health · Delivery Health · object | null

Read-only delivery state written by the dispatcher: consecutive_failures, first_failure_at, last_failure_at and last_failure_cause for the current run of failed deliveries, and paused_at and paused_reason when the run paused the webhook (is_active false). Re-enable with an update setting is_active true, which clears it.

created_at · string<date-time>

UTC timestamp when the webhook was created. Auto-generated at creation time. Immutable after creation. Format: ISO 8601 datetime.

updated_at · string<date-time>

UTC timestamp of the most recent webhook update. Updated automatically when event_types, channels, or is_active changes. Tracks configuration modifications. Format: ISO 8601 datetime.

Response

200

application/json

Successful Response

Configured webhook subscription for organization event notifications.

Webhooks enable real-time notifications when events occur in the system. Each webhook subscribes to specific event types and delivers notifications via one or more configured channels (Slack, email, HTTP).

Webhook Lifecycle: 1. Created with event_types and channels configured 2. is_active=True enables notification delivery 3. Events matching event_types trigger notifications to all channels 4. is_active=False temporarily pauses notifications without deletion 5. Webhook can be updated to add/remove event types or channels 6. Permanent deletion removes the webhook configuration

Use Cases: - Integrate Mixpeek events with external systems via HTTP webhooks - Notify teams in Slack when ingestion jobs complete - Send email alerts when critical failures occur - Trigger automated workflows based on state changes - Maintain audit trails by forwarding events to SIEM systems

Best Practices: - Subscribe only to events you need (reduces noise) - Use descriptive webhook_name for identification - Configure multiple channels for critical events (redundancy) - Set is_active=False to temporarily disable without losing config - Monitor webhook delivery failures via last_error tracking

webhook_name · string · required

REQUIRED. Human-readable name for the webhook. Displayed in dashboards, logs, and notification metadata. Should describe the webhook's purpose or destination. Format: 1-200 characters.

Required string length: 1 - 200

Examples:

"Slack Engineering Alerts"

"External System Integration"

"Audit Trail Logger"

"Production Monitoring"

event_types · enum<string>[] · required

REQUIRED. List of event types that trigger this webhook. When any of these events occur, notifications are sent to all channels. Must contain at least one event type. Common patterns: - ['object.created', 'object.updated'] for object lifecycle tracking - ['cluster.execution.completed', 'cluster.execution.failed'] for job monitoring - ['*'] for all events (use cautiously, high volume)

Minimum array length: 1

Webhook event types for real-time notifications.

These events are emitted when significant state changes occur in the system. Webhooks subscribe to specific event types and receive notifications via configured channels (email, Slack, HTTP webhooks).

Event Naming Convention: {resource}.{action}[.{sub-resource}[.{sub-action}]]

Examples: - object.created: New object ingested - collection.documents.written: Documents indexed - cluster.execution.completed: Cluster job finished

Cache Invalidation Annotations: Each event type includes a comment indicating recommended cache invalidation scope: - [KEY] = Invalidate specific document/object keys - [COLLECTION] = Invalidate collection-level cache - [NAMESPACE] = Invalidate namespace-level cache

Event Categories: - Object Lifecycle: Events for individual objects (create, update, delete) - Collection Lifecycle: Events for collections (create, update, delete, documents written) - Cluster Lifecycle: Events for clusters (create, update, delete, execution status) - Trigger Lifecycle: Events for cluster triggers (create, update, fire, execution status) - Taxonomy Lifecycle: Events for taxonomies (create, update, delete)

Use Cases: - Real-time sync with external systems - Audit trail and compliance logging - Automated workflows triggered by state changes - Cache invalidation for distributed systems - Notifications to team members via Slack/email

Available options: object.created, objects.created.batch, object.updated, object.deleted, document.created, document.updated, document.deleted, documents.updated.batch, documents.deleted.batch, collection.created, collection.updated, collection.deleted, collection.documents.written, collection.documents.batch_completed, cluster.created, cluster.updated, cluster.deleted, cluster.execution.started, cluster.execution.completed, cluster.execution.failed, trigger.created, trigger.updated, trigger.deleted, trigger.paused, trigger.resumed, trigger.fired, trigger.execution.completed, trigger.execution.failed, taxonomy.created, taxonomy.updated, taxonomy.deleted, alert.created, alert.updated, alert.deleted, alert.triggered, alert.execution.completed, alert.execution.failed, annotation.created, annotation.updated, annotation.deleted, resource.executed, resource.execution_failed, manifest.apply.resource_state

Examples:

[
  "object.created",
  "object.updated",
  "object.deleted"
]

[
  "cluster.execution.completed",
  "cluster.execution.failed"
]

["collection.documents.written"]

channels · WebhookChannel · object[] · required

REQUIRED. List of notification channels for event delivery. When an event occurs, notifications are sent to ALL configured channels. Must contain at least one channel. Multiple channels provide redundancy and multi-audience delivery. Example: Send to both Slack (team) and email (manager) for critical events.

Minimum array length: 1

Show child attributes

webhook_id · string

Unique identifier for the webhook. Auto-generated with 'wh_' prefix followed by secure random token. Format: wh_{16-character hex}. Used for API operations and event tracking.

Pattern: ^wh_[a-fA-F0-9]{16}$

Examples:

"wh_abc123def4567890"

"wh_1234567890abcdef"

resource_types · string[] | null

OPTIONAL. Deliver only events whose resource_type is one of these, for example ['retriever', 'taxonomy']. Applies to every event type: for resource.executed and resource.execution_failed the resource_type is the primitive that ran (it travels in the payload); for the per-kind types it is the first segment of the event type. Omitted or empty: no resource_type filter.

Example:

["retriever"]

is_active · boolean · default: true

Whether the webhook is currently active and should send notifications. True: Events trigger notifications to channels. False: Webhook is paused, no notifications sent but config preserved. Use to temporarily disable webhooks without losing configuration. Default: True

delivery_health · Delivery Health · object | null

Read-only delivery state written by the dispatcher: consecutive_failures, first_failure_at, last_failure_at and last_failure_cause for the current run of failed deliveries, and paused_at and paused_reason when the run paused the webhook (is_active false). Re-enable with an update setting is_active true, which clears it.

created_at · string<date-time>

UTC timestamp when the webhook was created. Auto-generated at creation time. Immutable after creation. Format: ISO 8601 datetime.

updated_at · string<date-time>

UTC timestamp of the most recent webhook update. Updated automatically when event_types, channels, or is_active changes. Tracks configuration modifications. Format: ISO 8601 datetime.