---
title: "Create or Clone Webhook"
method: POST
path: "/api/v2/webhooks"
tags: ["Webhooks"]
---

# Create or Clone Webhook

`POST /api/v2/webhooks`

Creates or clones a webhook. The clone_webhook_id query parameter is only required when cloning a webhook.
A request body is only required when creating a webhook.

Note that admins cannot clone webhooks created by Zendesk apps.

**Webhooks for trial accounts**: Zendesk trial accounts are limited to 10 webhooks.

## Query parameters

- `clone_webhook_id` string

## Request body

- WebhookCreateRequest
  - `webhook` Webhook, required
    - `id` string — An auto-generated webhook id
    - `name` string, required — Webhook name
    - `description` string — Webhook description
    - `endpoint` string, required — The destination URL that the webhook notifies when Zendesk events occur
    - `http_method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', required — HTTP method used for the webhook's requests. To subscribe the webhook to Zendesk events, this must be "POST"
    - `request_format` 'json' | 'xml' | 'form_encoded', required — The format of the data that the webhook will send. To subscribe the webhook to Zendesk events, this must be "json"
    - `status` 'active' | 'inactive', required — Current status of the webhook
    - `subscriptions` string[] — Event subscriptions for the webhook. To subscribe the webhook to Zendesk events, specify one or more event types. To connect the webhook to a trigger or automation, specify only "conditional_ticket_events" in the array
    - `authentication` union — Adds authentication to the webhook's HTTP requests, if not specified, the webhook will be unauthenticated
      - BasicAuthAuthentication — Basic authentication configuration
        - `type` 'basic_auth', required
        - `data` object
          - `username` string, required — Username for basic authentication
          - `password` string — Password for basic authentication
      - BearerTokenAuthentication — Bearer token authentication configuration
        - `type` 'bearer_token', required
        - `data` object
          - `token` string — Bearer token for authentication
      - ApiKeyAuthentication — API key authentication configuration
        - `type` 'api_key', required
        - `data` object
          - `name` string, required — Name of the API key parameter
          - `value` string — Value of the API key
        - `add_position` 'header' | 'query_string', required — Where to add the API key (header or query string)
    - `custom_headers` object — Custom headers to deliver additional non-credential info to destinations
    - `signing_secret` WebhookSigningSecret — Signing secret used to verify webhook requests
      - `algorithm` string — Signing algorithm (e.g., sha256)
      - `secret` string — The signing secret value
    - `external_source` object — External source by which a webhook is created, e.g. Zendesk Marketplace
      - `name` string — Name of the external source
      - `version` string — Version of the external source
    - `created_at` string, date-time — When the webhook was created
    - `created_by` string — id of the user who created the webhook. "-1" represents the Zendesk system
    - `updated_at` string, date-time — When the webhook was last updated
    - `updated_by` string — id of the user who last updated the webhook

## Response `201`

Webhook created successfully

- WebhookResponse
  - `webhook` Webhook
    - `id` string — An auto-generated webhook id
    - `name` string, required — Webhook name
    - `description` string — Webhook description
    - `endpoint` string, required — The destination URL that the webhook notifies when Zendesk events occur
    - `http_method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', required — HTTP method used for the webhook's requests. To subscribe the webhook to Zendesk events, this must be "POST"
    - `request_format` 'json' | 'xml' | 'form_encoded', required — The format of the data that the webhook will send. To subscribe the webhook to Zendesk events, this must be "json"
    - `status` 'active' | 'inactive', required — Current status of the webhook
    - `subscriptions` string[] — Event subscriptions for the webhook. To subscribe the webhook to Zendesk events, specify one or more event types. To connect the webhook to a trigger or automation, specify only "conditional_ticket_events" in the array
    - `authentication` union — Adds authentication to the webhook's HTTP requests, if not specified, the webhook will be unauthenticated
      - BasicAuthAuthentication — Basic authentication configuration
        - `type` 'basic_auth', required
        - `data` object
          - `username` string, required — Username for basic authentication
          - `password` string — Password for basic authentication
      - BearerTokenAuthentication — Bearer token authentication configuration
        - `type` 'bearer_token', required
        - `data` object
          - `token` string — Bearer token for authentication
      - ApiKeyAuthentication — API key authentication configuration
        - `type` 'api_key', required
        - `data` object
          - `name` string, required — Name of the API key parameter
          - `value` string — Value of the API key
        - `add_position` 'header' | 'query_string', required — Where to add the API key (header or query string)
    - `custom_headers` object — Custom headers to deliver additional non-credential info to destinations
    - `signing_secret` WebhookSigningSecret — Signing secret used to verify webhook requests
      - `algorithm` string — Signing algorithm (e.g., sha256)
      - `secret` string — The signing secret value
    - `external_source` object — External source by which a webhook is created, e.g. Zendesk Marketplace
      - `name` string — Name of the external source
      - `version` string — Version of the external source
    - `created_at` string, date-time — When the webhook was created
    - `created_by` string — id of the user who created the webhook. "-1" represents the Zendesk system
    - `updated_at` string, date-time — When the webhook was last updated
    - `updated_by` string — id of the user who last updated the webhook

## Other responses

- `400` — Bad Request
- `403` — Forbidden - Trial account webhook limit exceeded or insufficient permissions

## Changes

> 29 revisions in range; 1 not diffed.

- **2026-05-11** `a67ea66f0a52` — 3 breaking, 3 info
  - the response property `webhook/authentication/oneOf[#/components/schemas/ApiKeyAuthentication]/data` became optional for the status `201`
  - the response property `webhook/authentication/oneOf[#/components/schemas/BasicAuthAuthentication]/data` became optional for the status `201`
  - the response property `webhook/authentication/oneOf[#/components/schemas/BearerTokenAuthentication]/data` became optional for the status `201`
  - the request property `webhook/allOf[#/components/schemas/Webhook]/authentication/oneOf[#/components/schemas/ApiKeyAuthentication]/data` became optional
  - …2 more
- …earlier changes not shown

[Full history](https://skmtc.dev/botbrains-io/apis/support-api/changes/api/v2/webhooks/post.md)

---

[API](https://skmtc.dev/botbrains-io/apis/support-api.md) · [All operations](https://skmtc.dev/botbrains-io/apis/support-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/botbrains-io/support-api/revisions/d53eac07ba68/schema)