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

# Crear webhook de plantilla

> Registra un webhook de plantilla (independiente de la instancia)

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

## Conceptos

Crea un webhook de plantilla. No depende de ninguna instancia —el `instanceId` se guarda como `null` automáticamente— y recibe únicamente los eventos de plantilla de WhatsApp.

El campo `events` admite **solo** `UPDATE_TEMPLATE_STATUS` y `UPDATE_TEMPLATE_CATEGORY`. Cualquier evento que no sea de plantilla devuelve `422`.

### `payloadFormat` se ignora

En los webhooks de plantilla el formato es siempre `DEFAULT`. Puedes omitir el campo; si lo envías (con cualquier valor), se descarta de forma silenciosa y se persiste como `DEFAULT`.

### Firma HMAC

Si `signing: true`, el campo `secret` se genera y se devuelve **solo en esta respuesta**. Guárdalo de forma segura: no volverá a mostrarse.

<Warning>
  <EnterpriseText lang="es" />
</Warning>

<Note>
  Tras la creación, el enrutamiento puede tardar hasta unos 5 min en reflejar el cambio (TTL de la caché).
</Note>


## OpenAPI

````yaml es/webhooks/openapi-template.json POST /v1/webhooks
openapi: 3.1.0
info:
  title: Omni Z-API - Webhooks de plantilla
  description: >-
    API para crear y gestionar webhooks de plantilla: endpoints que reciben los
    eventos de plantilla de WhatsApp y no dependen de una instancia
    (`instanceId` se guarda como `null`). Requiere el rol ENTERPRISE. Conviven
    con las rutas de webhook por instancia o canal, que se mantienen sin
    cambios.
  version: 1.0.0
servers:
  - url: https://api.omni.z-api.io
security:
  - bearerAuth: []
paths:
  /v1/webhooks:
    post:
      tags:
        - Webhooks de plantilla
      summary: Crear webhook de plantilla
      description: >-
        Crea un webhook de plantilla. No depende de ninguna instancia
        (`instanceId` se guarda como `null`) y admite **solo** eventos de
        plantilla. El campo `payloadFormat` se ignora: el formato es siempre
        `DEFAULT`.
      operationId: createTemplateWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateWebhookRequest'
            examples:
              basic:
                summary: Básico — eventos de plantilla
                value:
                  url: https://destino/webhook
                  description: Webhook de plantilla
                  events:
                    - UPDATE_TEMPLATE_STATUS
                    - UPDATE_TEMPLATE_CATEGORY
                  signing: false
                  authType: NONE
              withSignature:
                summary: Con firma HMAC
                value:
                  url: https://destino/webhook
                  events:
                    - UPDATE_TEMPLATE_STATUS
                  signing: true
              withBearerAuth:
                summary: Con autenticación Bearer
                value:
                  url: https://destino/webhook
                  events:
                    - UPDATE_TEMPLATE_STATUS
                    - UPDATE_TEMPLATE_CATEGORY
                  auth:
                    type: BEARER
                    token: mi-token-secreto
      responses:
        '201':
          description: >-
            Webhook de plantilla creado correctamente. `channelId` e
            `instanceId` llegan como `null`. El campo `secret` se devuelve
            **solo en esta respuesta** cuando `signing` es `true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateWebhookCreatedResponse'
              example:
                id: 8F2C00000000000000000000000000A1
                channelId: null
                instanceId: null
                url: https://destino/webhook
                description: Webhook de plantilla
                events:
                  - UPDATE_TEMPLATE_STATUS
                  - UPDATE_TEMPLATE_CATEGORY
                status: ENABLED
                signing: false
                secret: null
                auth:
                  type: NONE
                  configured: false
                payloadFormat: DEFAULT
                customAttributes: {}
                createdAt: '2026-07-15T19:00:00.000+00:00'
                updatedAt: '2026-07-15T19:00:00.000+00:00'
        '400':
          description: >-
            Falta el header `Authorization` o la entrada es estructuralmente no
            válida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Authorization header is required
        '422':
          description: >-
            El rol no es ENTERPRISE, o el alcance de los eventos no es válido
            (evento que no es de plantilla)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                notEnterprise:
                  summary: Cuenta sin el rol ENTERPRISE
                  value:
                    error: This action requires ENTERPRISE role
                invalidScope:
                  summary: Evento que no es de plantilla
                  value:
                    error: >-
                      Global webhooks (without instance) accept only template
                      events
components:
  schemas:
    CreateTemplateWebhookRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          description: URL de destino de los eventos
          example: https://destino/webhook
        description:
          type: string
          description: Descripción opcional del webhook
          example: Webhook de plantilla
        events:
          type: array
          description: >-
            Solo eventos de plantilla. Es obligatorio al menos uno. Cualquier
            evento que no sea de plantilla devuelve `422`.
          minItems: 1
          items:
            $ref: '#/components/schemas/TemplateEvent'
          example:
            - UPDATE_TEMPLATE_STATUS
            - UPDATE_TEMPLATE_CATEGORY
        signing:
          type: boolean
          description: >-
            Habilita la firma HMAC-SHA256. Cuando es `true`, genera y devuelve
            un `secret` de 64 caracteres hexadecimales **solo en la creación o
            la actualización**.
          default: false
          example: false
        authType:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          description: Tipo de autenticación (forma plana). Alternativa al objeto `auth`.
          default: NONE
          example: NONE
        token:
          type: string
          description: Credencial para `BEARER` (forma plana)
        key:
          type: string
          description: Credencial para `API_KEY` (forma plana)
        auth:
          $ref: '#/components/schemas/WebhookAuth'
        payloadFormat:
          type: string
          enum:
            - DEFAULT
          description: >-
            **Ignorado** en los webhooks de plantilla: el formato es siempre
            `DEFAULT`. Se puede omitir; si se envía (con cualquier valor), se
            descarta y se persiste como `DEFAULT`.
          default: DEFAULT
          example: DEFAULT
        customAttributes:
          type: object
          description: Mapa libre de atributos extra
          additionalProperties: true
          example: {}
    TemplateWebhookCreatedResponse:
      allOf:
        - $ref: '#/components/schemas/TemplateWebhookResponse'
        - type: object
          properties:
            secret:
              type: string
              nullable: true
              description: >-
                Secret HMAC de 64 caracteres hexadecimales: se devuelve **solo**
                cuando `signing = true` en el create o el update. Es `null`
                cuando la firma está deshabilitada. Después no se podrá
                recuperar.
              example: null
    Error:
      type: object
      properties:
        error:
          type: string
    TemplateEvent:
      type: string
      enum:
        - UPDATE_TEMPLATE_STATUS
        - UPDATE_TEMPLATE_CATEGORY
      description: >-
        Eventos de plantilla admitidos: `UPDATE_TEMPLATE_STATUS` (actualización
        del estado de la plantilla: aprobada, rechazada, etc.) y
        `UPDATE_TEMPLATE_CATEGORY` (actualización de la categoría de la
        plantilla).
    WebhookAuth:
      type: object
      description: >-
        Forma anidada de la autenticación. Para `BASIC` usa
        `username`+`password`; para `CUSTOM_HEADER` usa
        `headerName`+`headerValue`.
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          example: BEARER
        token:
          type: string
          description: Token para `BEARER`
          example: mi-token-secreto
        key:
          type: string
          description: Clave para `API_KEY`
        username:
          type: string
          description: Usuario para `BASIC`
        password:
          type: string
          description: Contraseña para `BASIC`
        headerName:
          type: string
          description: Nombre del header para `CUSTOM_HEADER`
          example: X-Api-Key
        headerValue:
          type: string
          description: Valor del header para `CUSTOM_HEADER`
    TemplateWebhookResponse:
      type: object
      properties:
        id:
          type: string
          description: ID único del webhook de plantilla
          example: 8F2C00000000000000000000000000A1
        channelId:
          type: string
          nullable: true
          description: Siempre `null` en los webhooks de plantilla
          example: null
        instanceId:
          type: string
          nullable: true
          deprecated: true
          description: Obsoleto y siempre `null` en los webhooks de plantilla
          example: null
        url:
          type: string
          description: URL de destino de los eventos
          example: https://destino/webhook
        description:
          type: string
          nullable: true
          description: Descripción del webhook
          example: Webhook de plantilla
        events:
          type: array
          description: Eventos de plantilla configurados
          items:
            $ref: '#/components/schemas/TemplateEvent'
          example:
            - UPDATE_TEMPLATE_STATUS
            - UPDATE_TEMPLATE_CATEGORY
        status:
          type: string
          enum:
            - ENABLED
            - DISABLED
          description: Estado actual del webhook
          example: ENABLED
        signing:
          type: boolean
          description: Indica si la firma HMAC está habilitada
          example: false
        auth:
          $ref: '#/components/schemas/WebhookAuthInfo'
        payloadFormat:
          type: string
          enum:
            - DEFAULT
          description: Siempre `DEFAULT` en los webhooks de plantilla
          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: >-
        Resumen de la autenticación configurada: las credenciales no se
        devuelven por seguridad
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
            - CUSTOM_HEADER
          example: NONE
        configured:
          type: boolean
          description: '`true` cuando hay credenciales configuradas'
          example: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret Key generada en el panel de Seguridad de Omni Z-API

````