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

# Update Webhook

> Update a webhook. Omitted fields are unchanged; `event_types` replaces the subscribed events; explicit null clears a purchase date bound. The signing secret is unchanged.

[Subtotal Connector tool: update\_webhook](/docs/connector/tools#update_webhook)

## Access

Call this endpoint with your API key, or with a [Subtotal Connector](/docs/connector/introduction) OAuth token that includes `webhooks:write`. A token without `webhooks:write` receives `403 insufficient_scope`. [Partner app](/docs/partner-apps/introduction#fixed-permissions) tokens don't include it.

## Example

Pause a webhook:

```bash theme={null}
curl --request PATCH 'https://api.subtotal.com/webhooks/01JA7Q2W3E4R5T6Y7U8I9O0P1A' \
  --header "x-api-key: $SUBTOTAL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"is_active": false}'
```

The response is the updated webhook, in the same shape as [List webhooks](/docs/api-reference/webhooks/get-webhooks).

* Fields you omit are left unchanged.
* `event_types` replaces the subscribed events. Send the full list you want.
* Send `null` for `purchase_date_start` or `purchase_date_end` to clear that bound. Other fields can't be `null`.
* A new `url` must meet the same [requirements](/docs/api-reference/webhooks/create-webhook#url-requirements) as on create.
* The signing secret doesn't change.

## Errors

| Status | When |
| - | - |
| `404` | No webhook with this `webhook_id` on your account |
| `422` | A URL that doesn't meet the requirements, an unknown event type, an empty `event_types` list, `null` for a field other than a date bound, a name already used by another of your webhooks, or a date window whose start is after its end |


## OpenAPI

````yaml patch /webhooks/{webhook_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /webhooks/{webhook_id}:
    patch:
      tags:
        - webhooks
      summary: Update Webhook
      description: >-
        Update a webhook. Omitted fields are unchanged; `event_types` replaces
        the subscribed events; explicit null clears a purchase date bound. The
        signing secret is unchanged.
      operationId: update_webhook_webhooks__webhook_id__patch
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema:
            type: string
            title: Webhook Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookItem'
        '404':
          description: No webhook with this id on the account.
        '422':
          description: >-
            Invalid URL, unknown event type, inverted date window, duplicate
            name, or null field.
components:
  schemas:
    UpdateWebhookRequest:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 64
              minLength: 1
            - type: 'null'
          title: Name
        url:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
          title: Url
        is_active:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Active
        event_types:
          anyOf:
            - items:
                type: string
              type: array
              minItems: 1
            - type: 'null'
          title: Event Types
          description: Replaces the subscribed events.
        receive_simulated_events:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Receive Simulated Events
        purchase_date_start:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Purchase Date Start
        purchase_date_end:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Purchase Date End
      type: object
      title: UpdateWebhookRequest
      description: >-
        Omitted fields are unchanged; explicit null clears a purchase date
        bound.
    WebhookItem:
      properties:
        webhook_id:
          type: string
          title: Webhook Id
        name:
          type: string
          title: Name
        url:
          type: string
          title: Url
        is_active:
          type: boolean
          title: Is Active
        event_types:
          items:
            type: string
          type: array
          title: Event Types
          description: Subscribed event names, e.g. `purchase.created`.
        receive_simulated_events:
          type: boolean
          title: Receive Simulated Events
          description: Also deliver events from the simulator.
        purchase_date_start:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Purchase Date Start
          description: Only purchases on or after this date; null = unbounded.
        purchase_date_end:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Purchase Date End
          description: Only purchases on or before this date; null = unbounded.
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - webhook_id
        - name
        - url
        - is_active
        - event_types
        - receive_simulated_events
        - purchase_date_start
        - purchase_date_end
        - created_at
      title: WebhookItem
      description: A client webhook. The signing secret is never part of this shape.

````

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