> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update Webhook > Update an existing webhook. ## OpenAPI ````yaml put /v1/organizations/webhooks/{identifier} openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/organizations/webhooks/{identifier}: put: tags: - Webhooks summary: Update Webhook description: Update an existing webhook. operationId: update_webhook_v1_organizations_webhooks__identifier__put parameters: - name: identifier in: path required: true schema: type: string title: Identifier requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Webhook-Input' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Webhook-Output' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Webhook-Input: properties: webhook_id: type: string pattern: ^wh_[a-fA-F0-9]{16}$ title: Webhook Id description: >- 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. examples: - wh_abc123def4567890 - wh_1234567890abcdef webhook_name: type: string maxLength: 200 minLength: 1 title: Webhook Name description: >- 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. examples: - Slack Engineering Alerts - External System Integration - Audit Trail Logger - Production Monitoring internal_id: anyOf: - type: string - type: 'null' title: Internal Id description: >- 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}. event_types: items: $ref: '#/components/schemas/WebhookEventType' type: array minItems: 1 title: Event Types description: >- 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) examples: - - object.created - object.updated - object.deleted - - cluster.execution.completed - cluster.execution.failed - - collection.documents.written channels: items: $ref: '#/components/schemas/WebhookChannel-Input' type: array minItems: 1 title: Channels description: >- 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. is_active: type: boolean title: Is Active description: >- 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 default: true created_at: type: string format: date-time title: Created At description: >- UTC timestamp when the webhook was created. Auto-generated at creation time. Immutable after creation. Format: ISO 8601 datetime. updated_at: type: string format: date-time title: Updated At description: >- 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. type: object required: - webhook_name - event_types - channels title: Webhook description: >- 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 examples: - channels: - channel: slack configs: bot_token: xoxb-... channel_id: C0123456789 workspace_id: T0123456789 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_abc123def4 webhook_name: Engineering Slack Alerts - channels: - channel: slack configs: bot_token: xoxb-... channel_id: C0123456789 workspace_id: T0123456789 - channel: email configs: recipients: - oncall@example.com subject_template: 'CRITICAL: {event_type}' created_at: '2025-01-01T00:00:00Z' description: Multi-channel alerts for cluster failures event_types: - cluster.execution.failed - trigger.execution.failed is_active: true updated_at: '2025-01-15T10:30:00Z' webhook_id: wh_xyz789uvw0 webhook_name: Production Monitoring - channels: - channel: webhook configs: headers: Authorization: Bearer secret123 method: POST url: https://siem.company.com/webhooks/mixpeek created_at: '2025-01-01T00:00:00Z' description: External system integration via HTTP webhook event_types: - object.created - object.updated - object.deleted - collection.created - collection.deleted is_active: true updated_at: '2025-01-01T00:00:00Z' webhook_id: wh_int123ext4 webhook_name: SIEM Audit Trail Webhook-Output: properties: webhook_id: type: string pattern: ^wh_[a-fA-F0-9]{16}$ title: Webhook Id description: >- 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. examples: - wh_abc123def4567890 - wh_1234567890abcdef webhook_name: type: string maxLength: 200 minLength: 1 title: Webhook Name description: >- 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. examples: - Slack Engineering Alerts - External System Integration - Audit Trail Logger - Production Monitoring event_types: items: $ref: '#/components/schemas/WebhookEventType' type: array minItems: 1 title: Event Types description: >- 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) examples: - - object.created - object.updated - object.deleted - - cluster.execution.completed - cluster.execution.failed - - collection.documents.written channels: items: $ref: '#/components/schemas/WebhookChannel-Output' type: array minItems: 1 title: Channels description: >- 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. is_active: type: boolean title: Is Active description: >- 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 default: true created_at: type: string format: date-time title: Created At description: >- UTC timestamp when the webhook was created. Auto-generated at creation time. Immutable after creation. Format: ISO 8601 datetime. updated_at: type: string format: date-time title: Updated At description: >- 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. type: object required: - webhook_name - event_types - channels title: Webhook description: >- 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 examples: - channels: - channel: slack configs: bot_token: xoxb-... channel_id: C0123456789 workspace_id: T0123456789 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_abc123def4 webhook_name: Engineering Slack Alerts - channels: - channel: slack configs: bot_token: xoxb-... channel_id: C0123456789 workspace_id: T0123456789 - channel: email configs: recipients: - oncall@example.com subject_template: 'CRITICAL: {event_type}' created_at: '2025-01-01T00:00:00Z' description: Multi-channel alerts for cluster failures event_types: - cluster.execution.failed - trigger.execution.failed is_active: true updated_at: '2025-01-15T10:30:00Z' webhook_id: wh_xyz789uvw0 webhook_name: Production Monitoring - channels: - channel: webhook configs: headers: Authorization: Bearer secret123 method: POST url: https://siem.company.com/webhooks/mixpeek created_at: '2025-01-01T00:00:00Z' description: External system integration via HTTP webhook event_types: - object.created - object.updated - object.deleted - collection.created - collection.deleted is_active: true updated_at: '2025-01-01T00:00:00Z' webhook_id: wh_int123ext4 webhook_name: SIEM Audit Trail ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError WebhookEventType: type: string enum: - object.created - objects.created.batch - 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 - taxonomy.updated - taxonomy.deleted - alert.created - alert.updated - alert.deleted - alert.triggered - alert.execution.completed - alert.execution.failed - annotation.created - annotation.updated - annotation.deleted title: WebhookEventType description: >- 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 WebhookChannel-Input: properties: channel: $ref: '#/components/schemas/NotificationChannel' description: >- REQUIRED. The notification channel type for delivery. Determines which delivery mechanism is used (email, Slack, webhook). Must match the type of the configs field. configs: anyOf: - $ref: '#/components/schemas/EmailConfig-Input' - $ref: '#/components/schemas/SlackConfig' - $ref: '#/components/schemas/WebhookConfig' title: Configs description: >- REQUIRED. Channel-specific configuration for notification delivery. Type depends on the channel field: - EmailConfig for EMAIL channel (recipients, subject template, etc.) - SlackConfig for SLACK channel (workspace, channel, bot token) - WebhookConfig for WEBHOOK channel (URL, headers, auth). See respective config models for detailed field requirements. type: object required: - channel - configs title: WebhookChannel description: |- Notification channel configuration for webhook delivery. Defines how and where webhook event notifications should be delivered. Each webhook can have multiple channels configured for redundancy or different notification audiences. Supported Channels: - EMAIL: Send notifications via email to specified recipients - SLACK: Post messages to Slack channels or direct messages - WEBHOOK: HTTP POST to external endpoints (standard webhooks) Use Cases: - Route critical alerts to Slack and email simultaneously - Send audit trail events to external webhook endpoints - Notify team members via email for object lifecycle events - Post cluster completion status to Slack channels Requirements: - Channel type must match the config type (discriminated union) - Each config must have valid credentials/endpoints configured - Channel configs are validated at webhook creation time examples: - channel: slack configs: bot_token: xoxb-... channel_id: C0123456789 workspace_id: T0123456789 description: Slack notification channel - channel: email configs: recipients: - team@example.com - admin@example.com subject_template: 'Mixpeek Alert: {event_type}' description: Email notification channel - channel: webhook configs: headers: Authorization: Bearer token123 method: POST url: https://api.example.com/webhooks/mixpeek description: HTTP webhook channel WebhookChannel-Output: properties: channel: $ref: '#/components/schemas/NotificationChannel' description: >- REQUIRED. The notification channel type for delivery. Determines which delivery mechanism is used (email, Slack, webhook). Must match the type of the configs field. configs: anyOf: - $ref: >- #/components/schemas/shared__notifications__vendors__email__models__EmailConfig - $ref: '#/components/schemas/SlackConfig' - $ref: '#/components/schemas/WebhookConfig' title: Configs description: >- REQUIRED. Channel-specific configuration for notification delivery. Type depends on the channel field: - EmailConfig for EMAIL channel (recipients, subject template, etc.) - SlackConfig for SLACK channel (workspace, channel, bot token) - WebhookConfig for WEBHOOK channel (URL, headers, auth). See respective config models for detailed field requirements. type: object required: - channel - configs title: WebhookChannel description: |- Notification channel configuration for webhook delivery. Defines how and where webhook event notifications should be delivered. Each webhook can have multiple channels configured for redundancy or different notification audiences. Supported Channels: - EMAIL: Send notifications via email to specified recipients - SLACK: Post messages to Slack channels or direct messages - WEBHOOK: HTTP POST to external endpoints (standard webhooks) Use Cases: - Route critical alerts to Slack and email simultaneously - Send audit trail events to external webhook endpoints - Notify team members via email for object lifecycle events - Post cluster completion status to Slack channels Requirements: - Channel type must match the config type (discriminated union) - Each config must have valid credentials/endpoints configured - Channel configs are validated at webhook creation time examples: - channel: slack configs: bot_token: xoxb-... channel_id: C0123456789 workspace_id: T0123456789 description: Slack notification channel - channel: email configs: recipients: - team@example.com - admin@example.com subject_template: 'Mixpeek Alert: {event_type}' description: Email notification channel - channel: webhook configs: headers: Authorization: Bearer token123 method: POST url: https://api.example.com/webhooks/mixpeek description: HTTP webhook channel ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError NotificationChannel: type: string enum: - email - slack - webhook title: NotificationChannel description: Enum for notification delivery channels. EmailConfig-Input: properties: to_addresses: items: type: string type: array title: To Addresses description: Email addresses to send to subject_template: anyOf: - type: string - type: 'null' title: Subject Template description: Template for email subject body_template: anyOf: - type: string - type: 'null' title: Body Template description: Template for email body content_type: $ref: '#/components/schemas/NotificationContentType' description: Format of the email body default: html cc_addresses: items: type: string type: array title: Cc Addresses description: CC addresses bcc_addresses: items: type: string type: array title: Bcc Addresses description: BCC addresses type: object required: - to_addresses title: EmailConfig description: Configuration for email notifications. SlackConfig: properties: webhook_url: type: string title: Webhook Url description: Slack webhook URL channel: anyOf: - type: string - type: 'null' title: Channel description: Slack channel to send to username: anyOf: - type: string - type: 'null' title: Username description: Username to use for the message icon_emoji: anyOf: - type: string - type: 'null' title: Icon Emoji description: Emoji to use as the icon icon_url: anyOf: - type: string - type: 'null' title: Icon Url description: URL to an image to use as the icon blocks_template: anyOf: - type: string - type: 'null' title: Blocks Template description: Template for Slack blocks type: object required: - webhook_url title: SlackConfig description: Configuration for Slack notifications. WebhookConfig: properties: url: type: string title: Url description: The URL to which the webhook will be sent. headers: additionalProperties: type: string type: object title: Headers description: Custom headers to include in the webhook request. payload_template: anyOf: - additionalProperties: true type: object - type: 'null' title: Payload Template description: A Jinja2 template for the JSON payload. timeout: type: number title: Timeout description: Request timeout in seconds. default: 10 type: object required: - url title: WebhookConfig description: Configuration for webhook notifications. shared__notifications__vendors__email__models__EmailConfig: properties: to_addresses: items: type: string type: array title: To Addresses description: Email addresses to send to subject_template: anyOf: - type: string - type: 'null' title: Subject Template description: Template for email subject body_template: anyOf: - type: string - type: 'null' title: Body Template description: Template for email body content_type: $ref: '#/components/schemas/NotificationContentType' description: Format of the email body default: html cc_addresses: items: type: string type: array title: Cc Addresses description: CC addresses bcc_addresses: items: type: string type: array title: Bcc Addresses description: BCC addresses type: object required: - to_addresses title: EmailConfig description: Configuration for email notifications. NotificationContentType: type: string enum: - plain_text - html - markdown - json title: NotificationContentType description: Enum for content formats. ````