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

# Update template webhook

> Update the configuration of an existing template webhook

export const EnterpriseText = ({lang = 'pt'}) => ({
  pt: <>Este endpoint requer a role <strong>ENTERPRISE</strong> na sua conta.</>,
  en: <>This endpoint requires the <strong>ENTERPRISE</strong> role on your account.</>,
  es: <>Este endpoint requiere el rol <strong>ENTERPRISE</strong> en tu cuenta.</>
})[lang];

## Overview

Partially updates a template webhook's configuration. Only the fields sent in the body are updated — the rest remain unchanged.

### Updating events

When sending the `events` field, the list replaces the existing events and must contain **only** template events (otherwise → `422`):

```json theme={null}
{ "events": ["UPDATE_TEMPLATE_STATUS", "UPDATE_TEMPLATE_CATEGORY"] }
```

### HMAC signing

`signing: true` generates a new `secret` (returned only in this response); `signing: false` removes signing.

<Warning>
  The new `secret` is returned **only in this response**. Store it before closing the session.
</Warning>

### Temporarily disabling

```json theme={null}
{ "status": "DISABLED" }
```

To reactivate, send `{ "status": "ENABLED" }`.

### `payloadFormat` is still ignored

For template webhooks the format is always `DEFAULT`, even if sent in the update.

<Note>
  <EnterpriseText lang="en" />
</Note>

<Note>
  After the change, routing may take up to \~5 min to reflect (cache TTL).
</Note>


## OpenAPI

````yaml en/webhooks/openapi-template.json PATCH /v1/webhooks/{webhookId}
openapi: 3.1.0
info:
  title: Omni Z-API - Template Webhooks
  description: >-
    API to create and manage template webhooks — endpoints that receive WhatsApp
    template events and do not depend on an instance (`instanceId` stored as
    `null`). Requires ENTERPRISE role. Coexists with the per-instance/channel
    webhook routes, which remain unchanged.
  version: 1.0.0
servers:
  - url: https://api.omni.z-api.io
security:
  - bearerAuth: []
paths:
  /v1/webhooks/{webhookId}:
    patch:
      tags:
        - Template webhooks
      summary: Update template webhook
      description: >-
        Partially updates the template webhook. Only the fields sent are
        changed; omitted ones remain unchanged. If `events` is sent, it must
        contain **only** template events. The `payloadFormat` field is still
        ignored.
      operationId: updateTemplateWebhook
      parameters:
        - name: webhookId
          in: path
          required: true
          description: Template webhook ID
          schema:
            type: string
            example: 8F2C00000000000000000000000000A1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateWebhookRequest'
            examples:
              updateUrlAndStatus:
                summary: Update URL and disable
                value:
                  url: https://new-destination/webhook
                  status: DISABLED
              updateEvents:
                summary: Update template events
                value:
                  events:
                    - UPDATE_TEMPLATE_STATUS
                    - UPDATE_TEMPLATE_CATEGORY
              enableSignature:
                summary: Enable / rotate HMAC signing
                value:
                  signing: true
      responses:
        '200':
          description: >-
            Template webhook updated. The `secret` field is returned **only**
            when `signing = true` in this update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateWebhookCreatedResponse'
              example:
                id: 8F2C00000000000000000000000000A1
                channelId: null
                instanceId: null
                url: https://new-destination/webhook
                description: Template webhook
                events:
                  - UPDATE_TEMPLATE_STATUS
                  - UPDATE_TEMPLATE_CATEGORY
                status: DISABLED
                signing: false
                auth:
                  type: NONE
                  configured: false
                payloadFormat: DEFAULT
                customAttributes: {}
                createdAt: '2026-07-15T19:00:00.000+00:00'
                updatedAt: '2026-07-15T19:30:00.000+00:00'
        '400':
          description: Structurally invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Validation error
        '404':
          description: Webhook not found for the tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Webhook not found
        '422':
          description: Role is not ENTERPRISE; or invalid event scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Global webhooks (without instance) accept only template events
components:
  schemas:
    UpdateTemplateWebhookRequest:
      type: object
      description: All fields are optional — only the fields sent are updated.
      properties:
        url:
          type: string
          description: New destination URL
          example: https://new-destination/webhook
        description:
          type: string
          description: New description
        events:
          type: array
          description: >-
            If sent, replaces the event list — template events only (otherwise →
            `422`).
          items:
            $ref: '#/components/schemas/TemplateEvent'
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: '`DISABLED` pauses event delivery without deleting the webhook'
        signing:
          type: boolean
          description: '`true` generates a new `secret`; `false` removes signing'
        authType:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          description: '`NONE` clears authentication; the others reconfigure it'
        token:
          type: string
          description: Credential for `BEARER`
        key:
          type: string
          description: Credential for `API_KEY`
        auth:
          $ref: '#/components/schemas/WebhookAuth'
        payloadFormat:
          type: string
          enum:
            - DEFAULT
          description: '**Ignored** for template webhooks'
        customAttributes:
          type: object
          additionalProperties: true
    TemplateWebhookCreatedResponse:
      allOf:
        - $ref: '#/components/schemas/TemplateWebhookResponse'
        - type: object
          properties:
            secret:
              type: string
              nullable: true
              description: >-
                64-character hex HMAC secret — returned **only** when `signing =
                true` on create/update. `null` when signing is disabled. It
                cannot be retrieved afterwards.
              example: null
    Error:
      type: object
      properties:
        error:
          type: string
    TemplateEvent:
      type: string
      enum:
        - UPDATE_TEMPLATE_STATUS
        - UPDATE_TEMPLATE_CATEGORY
      description: >-
        Accepted template events: `UPDATE_TEMPLATE_STATUS` (template status
        update — approved/rejected etc.) and `UPDATE_TEMPLATE_CATEGORY`
        (template category update).
    WebhookAuth:
      type: object
      description: >-
        Nested authentication form. For `BASIC` use `username`+`password`; for
        `CUSTOM_HEADER` use `headerName`+`headerValue`.
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          example: BEARER
        token:
          type: string
          description: Token for `BEARER`
          example: my-secret-token
        key:
          type: string
          description: Key for `API_KEY`
        username:
          type: string
          description: Username for `BASIC`
        password:
          type: string
          description: Password for `BASIC`
        headerName:
          type: string
          description: Header name for `CUSTOM_HEADER`
          example: X-Api-Key
        headerValue:
          type: string
          description: Header value for `CUSTOM_HEADER`
    TemplateWebhookResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique template webhook ID
          example: 8F2C00000000000000000000000000A1
        channelId:
          type: string
          nullable: true
          description: Always `null` for template webhooks
          example: null
        instanceId:
          type: string
          nullable: true
          deprecated: true
          description: Deprecated and always `null` for template webhooks
          example: null
        url:
          type: string
          description: Destination URL for the events
          example: https://destination/webhook
        description:
          type: string
          nullable: true
          description: Webhook description
          example: Template webhook
        events:
          type: array
          description: Configured template events
          items:
            $ref: '#/components/schemas/TemplateEvent'
          example:
            - UPDATE_TEMPLATE_STATUS
            - UPDATE_TEMPLATE_CATEGORY
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: Current webhook status
          example: ENABLED
        signing:
          type: boolean
          description: Indicates whether HMAC signing is enabled
          example: false
        auth:
          $ref: '#/components/schemas/WebhookAuthInfo'
        payloadFormat:
          type: string
          enum:
            - DEFAULT
          description: Always `DEFAULT` for template webhooks
          example: DEFAULT
        customAttributes:
          type: object
          additionalProperties: true
          example: {}
        createdAt:
          type: string
          format: date-time
          example: '2026-07-15T19:00:00.000+00:00'
        updatedAt:
          type: string
          format: date-time
          example: '2026-07-15T19:00:00.000+00:00'
    WebhookAuthInfo:
      type: object
      description: >-
        Summary of the configured authentication — credentials are not returned
        for security reasons
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          example: NONE
        configured:
          type: boolean
          description: '`true` when credentials are configured'
          example: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret Key generated in the Omni Z-API Security panel

````