> ## 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.

# Atualizar webhook de template

> Atualize a configuração de um webhook de template existente

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];

## Conceituação

Atualiza parcialmente a configuração de um webhook de template. Apenas os campos enviados no body são atualizados — os demais permanecem inalterados.

### Atualizar eventos

Se enviar o campo `events`, a lista substitui os eventos existentes e deve conter **somente** eventos de template (senão → `422`):

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

### Assinatura HMAC

`signing: true` gera um novo `secret` (retornado apenas nesta resposta); `signing: false` remove a assinatura.

<Warning>
  O novo `secret` é retornado **apenas nesta resposta**. Armazene-o antes de fechar a sessão.
</Warning>

### Desabilitar temporariamente

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

Para reativar, envie `{ "status": "ENABLED" }`.

### `payloadFormat` continua ignorado

Para webhooks de template o formato é sempre `DEFAULT`, mesmo que enviado na atualização.

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

<Note>
  Após a alteração, o roteamento pode levar até \~5 min para refletir (TTL de cache).
</Note>


## OpenAPI

````yaml pt/webhooks/openapi-template.json PATCH /v1/webhooks/{webhookId}
openapi: 3.1.0
info:
  title: Omni Z-API - Webhooks de Template
  description: >-
    API para criar e gerenciar webhooks de template — endpoints que recebem os
    eventos de template do WhatsApp e não dependem de uma instância
    (`instanceId` gravado como `null`). Requer role ENTERPRISE. Convivem com as
    rotas de webhook por instância/canal, que permanecem inalteradas.
  version: 1.0.0
servers:
  - url: https://api.omni.z-api.io
security:
  - bearerAuth: []
paths:
  /v1/webhooks/{webhookId}:
    patch:
      tags:
        - Webhooks de template
      summary: Atualizar webhook de template
      description: >-
        Atualiza parcialmente o webhook de template. Apenas os campos enviados
        são alterados; os omitidos permanecem inalterados. Se `events` for
        enviado, deve conter **somente** eventos de template. O campo
        `payloadFormat` continua sendo ignorado.
      operationId: updateTemplateWebhook
      parameters:
        - name: webhookId
          in: path
          required: true
          description: ID do webhook de template
          schema:
            type: string
            example: 8F2C00000000000000000000000000A1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateWebhookRequest'
            examples:
              updateUrlAndStatus:
                summary: Atualizar URL e desabilitar
                value:
                  url: https://novo-destino/webhook
                  status: DISABLED
              updateEvents:
                summary: Atualizar eventos de template
                value:
                  events:
                    - UPDATE_TEMPLATE_STATUS
                    - UPDATE_TEMPLATE_CATEGORY
              enableSignature:
                summary: Habilitar / rotacionar assinatura HMAC
                value:
                  signing: true
      responses:
        '200':
          description: >-
            Webhook de template atualizado. O campo `secret` é retornado
            **apenas** quando `signing = true` nesta atualização.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateWebhookCreatedResponse'
              example:
                id: 8F2C00000000000000000000000000A1
                channelId: null
                instanceId: null
                url: https://novo-destino/webhook
                description: Webhook de template
                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: Entrada estruturalmente inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Validation error
        '404':
          description: Webhook não encontrado para o tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Webhook not found
        '422':
          description: Role não ENTERPRISE; ou escopo de eventos inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Global webhooks (without instance) accept only template events
components:
  schemas:
    UpdateTemplateWebhookRequest:
      type: object
      description: >-
        Todos os campos são opcionais — apenas os campos enviados são
        atualizados.
      properties:
        url:
          type: string
          description: Nova URL de destino
          example: https://novo-destino/webhook
        description:
          type: string
          description: Nova descrição
        events:
          type: array
          description: >-
            Se enviado, substitui a lista de eventos — somente eventos de
            template (senão → `422`).
          items:
            $ref: '#/components/schemas/TemplateEvent'
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: '`DISABLED` pausa a entrega de eventos sem excluir o webhook'
        signing:
          type: boolean
          description: '`true` gera um novo `secret`; `false` remove a assinatura'
        authType:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          description: '`NONE` limpa a autenticação; os demais reconfiguram'
        token:
          type: string
          description: Credencial para `BEARER`
        key:
          type: string
          description: Credencial para `API_KEY`
        auth:
          $ref: '#/components/schemas/WebhookAuth'
        payloadFormat:
          type: string
          enum:
            - DEFAULT
          description: '**Ignorado** para webhooks de template'
        customAttributes:
          type: object
          additionalProperties: true
    TemplateWebhookCreatedResponse:
      allOf:
        - $ref: '#/components/schemas/TemplateWebhookResponse'
        - type: object
          properties:
            secret:
              type: string
              nullable: true
              description: >-
                Segredo HMAC de 64 caracteres hex — retornado **apenas** quando
                `signing = true` no create/update. `null` quando a assinatura
                está desabilitada. Não poderá ser recuperado depois.
              example: null
    Error:
      type: object
      properties:
        error:
          type: string
    TemplateEvent:
      type: string
      enum:
        - UPDATE_TEMPLATE_STATUS
        - UPDATE_TEMPLATE_CATEGORY
      description: >-
        Eventos de template aceitos: `UPDATE_TEMPLATE_STATUS` (atualização de
        status do template — aprovado/rejeitado etc.) e
        `UPDATE_TEMPLATE_CATEGORY` (atualização de categoria do template).
    WebhookAuth:
      type: object
      description: >-
        Forma aninhada da autenticação. Para `BASIC` use `username`+`password`;
        para `CUSTOM_HEADER` use `headerName`+`headerValue`.
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          example: BEARER
        token:
          type: string
          description: Token para `BEARER`
          example: meu-token-secreto
        key:
          type: string
          description: Chave para `API_KEY`
        username:
          type: string
          description: Usuário para `BASIC`
        password:
          type: string
          description: Senha para `BASIC`
        headerName:
          type: string
          description: Nome do header para `CUSTOM_HEADER`
          example: X-Api-Key
        headerValue:
          type: string
          description: Valor do header para `CUSTOM_HEADER`
    TemplateWebhookResponse:
      type: object
      properties:
        id:
          type: string
          description: ID único do webhook de template
          example: 8F2C00000000000000000000000000A1
        channelId:
          type: string
          nullable: true
          description: Sempre `null` para webhooks de template
          example: null
        instanceId:
          type: string
          nullable: true
          deprecated: true
          description: Descontinuado e sempre `null` para webhooks de template
          example: null
        url:
          type: string
          description: URL de destino dos eventos
          example: https://destino/webhook
        description:
          type: string
          nullable: true
          description: Descrição do webhook
          example: Webhook de template
        events:
          type: array
          description: Eventos de template configurados
          items:
            $ref: '#/components/schemas/TemplateEvent'
          example:
            - UPDATE_TEMPLATE_STATUS
            - UPDATE_TEMPLATE_CATEGORY
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: Status atual do webhook
          example: ENABLED
        signing:
          type: boolean
          description: Indica se a assinatura HMAC está habilitada
          example: false
        auth:
          $ref: '#/components/schemas/WebhookAuthInfo'
        payloadFormat:
          type: string
          enum:
            - DEFAULT
          description: Sempre `DEFAULT` para webhooks de template
          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: >-
        Resumo da autenticação configurada — credenciais não são retornadas por
        segurança
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          example: NONE
        configured:
          type: boolean
          description: '`true` quando credenciais estão configuradas'
          example: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret Key gerada no painel de Segurança do Omni Z-API

````