> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protodesk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a webhook subscription



## OpenAPI

````yaml PATCH /webhooks/{webhookId}
openapi: 3.1.0
info:
  title: Protodesk API
  version: 0.1.0
  description: >
    The Protodesk Platform API: sync your customers in, attach your own business
    objects (orders, bookings, listings) to conversations, post and read
    messages across channels, and receive every workspace event via signed
    webhooks or a resumable SSE stream.


    Authenticate every request with a workspace-scoped API key: `Authorization:
    Bearer pk_live_...`. Create endpoints accept an `Idempotency-Key` header so
    retries are always safe. Lists use opaque cursor pagination (`data` /
    `hasMore` / `nextCursor`).


    Task-oriented guides: [docs.protodesk.io](https://docs.protodesk.io).
servers:
  - url: https://api.protodesk.io/v1
    description: Production
  - url: http://localhost:8080/v1
    description: Local development
security: []
tags:
  - name: Customers
    description: People or companies contacting a workspace across channels.
  - name: Conversations
    description: Customer conversations attached to channels and external business objects.
  - name: Messages
    description: Customer, agent, AI, system, and internal messages inside conversations.
  - name: Channel identities
    description: >-
      The same customer across WhatsApp, email, chat, and more — linked
      identities per channel.
  - name: Statuses & priorities
    description: The workspace's conversation statuses and priority levels.
  - name: Assignments
    description: >-
      Who a conversation has been assigned to, over time. Assign via POST
      /conversations/{conversationId}/assign.
  - name: Webhooks
    description: Webhook subscriptions for receiving workspace events.
  - name: Realtime
    description: Server-sent event stream of workspace events.
  - name: API Keys
    description: Create, list, and revoke workspace API keys.
  - name: Account
    description: The workspace and scopes behind your API key.
  - name: System
    description: Service metadata and health endpoints.
paths:
  /webhooks/{webhookId}:
    patch:
      tags:
        - Webhooks
      summary: Update a webhook subscription
      operationId: updateWebhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema:
            type: string
            example: wh_x6q5vl75f5d53m7oet2k4r5w6a
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Updated webhook subscription.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        default:
          $ref: '#/components/responses/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    UpdateWebhookRequest:
      type: object
      minProperties: 1
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint that will receive signed webhook deliveries.
          example: https://example.com/protodesk/webhooks
        events:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WebhookEvent'
        status:
          $ref: '#/components/schemas/WebhookStatus'
        metadata:
          type: object
          additionalProperties: true
          description: Replaces the full webhook metadata object.
          example:
            source: owner_app
    WebhookSubscription:
      type: object
      required:
        - id
        - url
        - events
        - status
        - metadata
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: wh_x6q5vl75f5d53m7oet2k4r5w6a
        url:
          type: string
          format: uri
          example: https://example.com/protodesk/webhooks
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEvent'
        status:
          $ref: '#/components/schemas/WebhookStatus'
        secret:
          type:
            - string
            - 'null'
          description: >-
            Signing secret; returned only when the webhook is created, null on
            reads.
          example: whsec_pz6kyr2ftwsn6c6q3a4oky2d35txmgaj3t35u2quy4ielzqro3za
        metadata:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    WebhookEvent:
      type: string
      enum:
        - customer.created
        - customer.updated
        - conversation.created
        - conversation.updated
        - conversation.assigned
        - conversation.resolved
        - conversation.read
        - message.created
        - message.delivered
        - message.failed
    WebhookStatus:
      type: string
      enum:
        - active
        - disabled
    ErrorEnvelope:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
        - code
        - message
        - requestId
      properties:
        code:
          type: string
          example: route.not_found
        message:
          type: string
          example: Not found
        requestId:
          type: string
          example: req_x6q5vl75f5d53m7oet2k4r5w6a
  headers:
    RequestId:
      description: Request id for tracing this request in logs and support.
      schema:
        type: string
        example: req_x6q5vl75f5d53m7oet2k4r5w6a
    RateLimitLimit:
      description: >-
        Request budget for the route class (read or write) applied to this
        request.
      schema:
        type: integer
        example: 40
    RateLimitRemaining:
      description: Requests remaining in the current budget after this request.
      schema:
        type: integer
        example: 39
    RateLimitReset:
      description: Seconds until the budget refills to its full limit.
      schema:
        type: integer
        example: 1
    RetryAfter:
      description: Seconds to wait before retrying, sent with 429 responses.
      schema:
        type: integer
        example: 1
  responses:
    Error:
      description: >-
        Error response. All /v1 responses carry RateLimit-Limit,
        RateLimit-Remaining, and RateLimit-Reset headers. A 429
        (rate_limit.exceeded) additionally carries Retry-After. Request bodies
        exceeding the route-class limit (1KB reads, 64KB writes) return 413
        (request.body_too_large).
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: Protodesk API key
      description: >
        Use a workspace API key in the Authorization header. Keys use
        pk_live_<key_id>_<secret> for production and pk_test_<key_id>_<secret>
        for test mode.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.