Skip to main content
PUT
/
v1
/
organizations
/
webhooks
/
{identifier}
Update Webhook
curl --request PUT \
  --url https://api.mixpeek.com/v1/organizations/webhooks/{identifier} \
  --header 'Content-Type: application/json' \
  --data '
{
  "webhook_name": "<string>",
  "event_types": [
    "object.created"
  ],
  "channels": [
    {
      "channel": "email",
      "configs": {
        "to_addresses": [
          "<string>"
        ],
        "subject_template": "<string>",
        "body_template": "<string>",
        "content_type": "html",
        "cc_addresses": [
          "<string>"
        ],
        "bcc_addresses": [
          "<string>"
        ]
      }
    }
  ],
  "webhook_id": "<string>",
  "internal_id": "<string>",
  "is_active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}
'
{
  "webhook_name": "<string>",
  "event_types": [
    "object.created"
  ],
  "channels": [
    {
      "channel": "email",
      "configs": {
        "to_addresses": [
          "<string>"
        ],
        "subject_template": "<string>",
        "body_template": "<string>",
        "content_type": "html",
        "cc_addresses": [
          "<string>"
        ],
        "bcc_addresses": [
          "<string>"
        ]
      }
    }
  ],
  "webhook_id": "<string>",
  "is_active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Headers

​
Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

Path Parameters

​
identifier
string
required

Body

application/json

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, SMS).

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, SMS).

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,
object.updated,
object.deleted,
collection.created,
collection.updated,
collection.deleted,
collection.documents.written,
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
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
​
webhook_id
string

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

Examples:

"wh_abc123def4"

"wh_xyz789uvw0"

​
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}.

​
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

​
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

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, SMS).

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, SMS).

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,
object.updated,
object.deleted,
collection.created,
collection.updated,
collection.deleted,
collection.documents.written,
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
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
​
webhook_id
string

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

Examples:

"wh_abc123def4"

"wh_xyz789uvw0"

​
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

​
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.