Crear webhook de plantilla

curl --request POST \
  --url https://api.omni.z-api.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.suempresa.com/webhooks/templates",
  "description": "Webhook de plantilla",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "signing": false,
  "authType": "NONE"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://app.suempresa.com/webhooks/templates",
  "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"
}

POST

webhooks

curl --request POST \
  --url https://api.omni.z-api.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.suempresa.com/webhooks/templates",
  "description": "Webhook de plantilla",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "signing": false,
  "authType": "NONE"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://app.suempresa.com/webhooks/templates",
  "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"
}

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. La firma llega en el header x-webhook-signature y se calcula sobre una cadena canónica de cinco campos, no solo sobre el cuerpo. Consulta Firma HMAC.

Validaciones

La petición se rechaza con 400, sin guardar nada, en estos casos:

Caso	Respuesta
`url` ausente o en blanco	`{"error": "URL is required"}`
`url` con formato no válido, o con un host que no resuelve solo a direcciones públicas	consulta URL del webhook
`events` ausente o vacío	`{"error": "At least one event is required"}`
Un elemento de `events` nulo, en blanco o con un nombre que no existe	`{"error": "events contains an unknown or empty event name"}`
`auth.type` `CUSTOM_HEADER` sin `auth.headerName`	`{"error": "Header name is required for CUSTOM_HEADER auth type"}`
Autenticación distinta de `NONE` sin la credencial de su tipo	`{"error": "Credentials are required when auth type is not NONE"}`

El nombre del evento se acepta en mayúsculas o minúsculas. La respuesta de nombre no válido no repite el valor enviado.

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

Autorizaciones

Authorization

string

header

requerido

Secret Key generada en el panel de Seguridad de Omni Z-API

Cuerpo

application/json

url

string

requerido

URL de destino de los eventos: absoluta, http o https, de hasta 2048 caracteres. El host debe existir en el DNS y resolver solo a direcciones públicas; si no, 400.

Ejemplo:

"https://app.suempresa.com/webhooks/templates"

events

enum<string>[]

requerido

Solo eventos de plantilla. Es obligatorio al menos uno. Cualquier evento que no sea de plantilla devuelve 422; un nombre inexistente, nulo o en blanco devuelve 400.

Minimum array length: 1

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

Opciones disponibles:

UPDATE_TEMPLATE_STATUS,

UPDATE_TEMPLATE_CATEGORY

Ejemplo:

[
  "UPDATE_TEMPLATE_STATUS",
  "UPDATE_TEMPLATE_CATEGORY"
]

description

string

Descripción opcional del webhook

Ejemplo:

"Webhook de plantilla"

signing

boolean

predeterminado:false

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.

Ejemplo:

false

authType

enum<string>

predeterminado:NONE

Tipo de autenticación (forma plana). Alternativa al objeto auth.

Opciones disponibles:

NONE,

BEARER,

API_KEY,

BASIC,

CUSTOM_HEADER

Ejemplo:

"NONE"

token

string

Credencial para BEARER (forma plana)

key

string

Credencial para API_KEY (forma plana)

auth

object

Forma anidada de la autenticación. Para BASIC usa username+password; para CUSTOM_HEADER usa headerName+headerValue.

Show child attributes

payloadFormat

enum<string>

predeterminado:DEFAULT

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.

Opciones disponibles:

DEFAULT

Ejemplo:

"DEFAULT"

customAttributes

object

Mapa libre de atributos extra

Ejemplo:

{}

Respuesta

Webhook de plantilla creado correctamente. channelId e instanceId llegan como null. El campo secret se devuelve solo en esta respuesta cuando signing es true.

string

ID único del webhook de plantilla

Ejemplo:

"8F2C00000000000000000000000000A1"

channelId

string | null

Siempre null en los webhooks de plantilla

Ejemplo:

null

instanceId

string | null

obsoleto

Obsoleto y siempre null en los webhooks de plantilla

Ejemplo:

null

url

string

URL de destino de los eventos

Ejemplo:

"https://app.suempresa.com/webhooks/templates"

description

string | null

Descripción del webhook

Ejemplo:

"Webhook de plantilla"

events

enum<string>[]

Eventos de plantilla configurados Un evento guardado que la API todavía no conoce no aparece aquí.

Opciones disponibles:

UPDATE_TEMPLATE_STATUS,

UPDATE_TEMPLATE_CATEGORY

Ejemplo:

[
  "UPDATE_TEMPLATE_STATUS",
  "UPDATE_TEMPLATE_CATEGORY"
]

status

enum<string>

Estado actual del webhook

Opciones disponibles:

ENABLED,

DISABLED

Ejemplo:

"ENABLED"

signing

boolean

Indica si la firma HMAC está habilitada

Ejemplo:

false

auth

object

Resumen de la autenticación configurada: las credenciales no se devuelven por seguridad

Show child attributes

payloadFormat

enum<string>

Siempre DEFAULT en los webhooks de plantilla

Opciones disponibles:

DEFAULT

Ejemplo:

"DEFAULT"

customAttributes

object

Ejemplo:

{}

createdAt

string<date-time>

Ejemplo:

"2026-07-15T19:00:00.000+00:00"

updatedAt

string<date-time>

Ejemplo:

"2026-07-15T19:00:00.000+00:00"

secret

string | null

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.

Ejemplo:

null

Canales

Mensajes

Plantillas (WhatsApp)

Flows (WhatsApp)

Webhooks

Crear webhook de plantilla

Conceptos

`payloadFormat` se ignora

Firma HMAC

Validaciones

Autorizaciones

Cuerpo

Respuesta

​Conceptos

​payloadFormat se ignora

​Firma HMAC

​Validaciones

Autorizaciones

Cuerpo

Respuesta

Conceptos

`payloadFormat` se ignora

Firma HMAC

Validaciones