---
title: "Update Webhook"
method: PUT
path: "/v1/organizations/webhooks/{identifier}"
tags: ["Webhooks"]
---

# Update Webhook

`PUT /v1/organizations/webhooks/{identifier}`

Update an existing webhook.

## Path parameters

- `identifier` string, required

## Request body

- WebhookInput — 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_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.
  - `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.
  - `internal_id` string, nullable — 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` WebhookEventType[], 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)
  - `channels` WebhookChannelInput[], 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.
    - `channel` 'email' | 'slack' | 'webhook', required — Enum for notification delivery channels.
    - `configs` union, required — 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.
      - EmailConfigInput — Configuration for email notifications.
        - `to_addresses` string[], required — Email addresses to send to
        - `subject_template` string, nullable — Template for email subject
        - `body_template` string, nullable — Template for email body
        - `content_type` 'plain_text' | 'html' | 'markdown' | 'json' — Enum for content formats.
        - `cc_addresses` string[] — CC addresses
        - `bcc_addresses` string[] — BCC addresses
      - SlackConfig — Configuration for Slack notifications.
        - `webhook_url` string, required — Slack webhook URL
        - `channel` string, nullable — Slack channel to send to
        - `username` string, nullable — Username to use for the message
        - `icon_emoji` string, nullable — Emoji to use as the icon
        - `icon_url` string, nullable — URL to an image to use as the icon
        - `blocks_template` string, nullable — Template for Slack blocks
      - WebhookConfig — Configuration for webhook notifications.
        - `url` string, required — The URL to which the webhook will be sent.
        - `headers` object — Custom headers to include in the webhook request.
        - `payload_template` object, nullable — A Jinja2 template for the JSON payload.
        - `timeout` number — Request timeout in seconds.
  - `is_active` boolean — 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 `200`

Successful Response

- WebhookOutput — 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_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.
  - `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.
  - `event_types` WebhookEventType[], 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)
  - `channels` WebhookChannelOutput[], 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.
    - `channel` 'email' | 'slack' | 'webhook', required — Enum for notification delivery channels.
    - `configs` union, required — 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.
      - SharedNotificationsVendorsEmailModelsEmailConfig — Configuration for email notifications.
        - `to_addresses` string[], required — Email addresses to send to
        - `subject_template` string, nullable — Template for email subject
        - `body_template` string, nullable — Template for email body
        - `content_type` 'plain_text' | 'html' | 'markdown' | 'json' — Enum for content formats.
        - `cc_addresses` string[] — CC addresses
        - `bcc_addresses` string[] — BCC addresses
      - SlackConfig — Configuration for Slack notifications.
        - `webhook_url` string, required — Slack webhook URL
        - `channel` string, nullable — Slack channel to send to
        - `username` string, nullable — Username to use for the message
        - `icon_emoji` string, nullable — Emoji to use as the icon
        - `icon_url` string, nullable — URL to an image to use as the icon
        - `blocks_template` string, nullable — Template for Slack blocks
      - WebhookConfig — Configuration for webhook notifications.
        - `url` string, required — The URL to which the webhook will be sent.
        - `headers` object — Custom headers to include in the webhook request.
        - `payload_template` object, nullable — A Jinja2 template for the JSON payload.
        - `timeout` number — Request timeout in seconds.
  - `is_active` boolean — 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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/04b379bdbb7c/schema)