Crear webhook

curl --request POST \
  --url https://api.omni.z-api.io/v1/channels/{channelId}/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.suempresa.com/webhooks/omni-zapi",
  "events": [
    "MESSAGE_RECEIVED"
  ]
}
'

{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "channelId": "019E4C54B1B375A28970B605CA9B03C3",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.suempresa.com/webhooks/omni-zapi",
  "description": null,
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_STATUS"
  ],
  "status": "ENABLED",
  "signing": true,
  "secret": "a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab",
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2025-01-15T10:30:00.000+0000",
  "updatedAt": "2025-01-15T10:30:00.000+0000"
}

POST

channels

{channelId}

webhooks

curl --request POST \
  --url https://api.omni.z-api.io/v1/channels/{channelId}/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.suempresa.com/webhooks/omni-zapi",
  "events": [
    "MESSAGE_RECEIVED"
  ]
}
'

{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "channelId": "019E4C54B1B375A28970B605CA9B03C3",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.suempresa.com/webhooks/omni-zapi",
  "description": null,
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_STATUS"
  ],
  "status": "ENABLED",
  "signing": true,
  "secret": "a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab",
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2025-01-15T10:30:00.000+0000",
  "updatedAt": "2025-01-15T10:30:00.000+0000"
}

Conceptos

Registra un nuevo endpoint de webhook en el canal. A partir de su creación, Omni Z-API empieza a enviar los eventos configurados a la URL indicada. Un canal puede tener varios webhooks, algo útil para enviar eventos distintos a sistemas distintos o para mantener webhooks con formatos diferentes.

Firma HMAC

Si signing: true, el campo secret se genera automáticamente y se devuelve solo en esta respuesta. Guárdalo de forma segura: no volverá a mostrarse en ninguna otra llamada. Usa el secret para verificar en tu servidor la autenticidad de las peticiones recibidas. 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 para la cadena exacta y el código de validación.

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.

El channelId se obtiene a través del endpoint Crear canal.

Autorizaciones

Authorization

string

header

requerido

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

Parámetros de ruta

channelId

string

requerido

ID del canal

Ejemplo:

"019E4C54B1B375A28970B605CA9B03C3"

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/omni-zapi"

events

enum<string>[]

requerido

Tipos de evento que se van a recibir. Es obligatorio al menos uno. El nombre se acepta en mayúsculas o minúsculas; un nombre inexistente, nulo o en blanco devuelve 400.

Opciones disponibles:

MESSAGE_RECEIVED,

MESSAGE_DELIVERY,

MESSAGE_STATUS,

RECEIVED_STATUS,

RECEIVED_AND_DELIVERY,

CONNECTED,

DISCONNECTED,

PRESENCE_CHAT,

INITIAL_DATA,

BLOCK

Ejemplo:

["MESSAGE_RECEIVED", "MESSAGE_STATUS"]

description

string

Descripción opcional del webhook

Ejemplo:

"Webhook principal de producción"

signing

boolean

predeterminado:false

Habilita la firma HMAC-SHA256. Cuando es true, se genera un secret de 64 caracteres hexadecimales que se devuelve solo en la creación o la actualización. Úsalo para verificar la autenticidad de las peticiones recibidas.

Ejemplo:

true

auth

object

Configura cómo se autentica Omni Z-API al llamar a tu URL

Show child attributes

payloadFormat

enum<string>

predeterminado:DEFAULT

Formato del payload entregado al webhook. DEFAULT es el formato de Omni Z-API; Z_API mantiene la estructura de Z-API para quienes migran; CHATWOOT lo entrega en el formato que espera Chatwoot.

Opciones disponibles:

DEFAULT,

Z_API,

CHATWOOT

Ejemplo:

"DEFAULT"

customAttributes

object

Atributos extra

Ejemplo:

{}

Respuesta

Webhook creado correctamente. El campo secret se devuelve solo en esta respuesta cuando signing es true; guárdalo de forma segura.

string

ID único del webhook

Ejemplo:

"A1B2C3D4E5F6789012345678901234AB"

channelId

string

ID del canal al que pertenece el webhook

Ejemplo:

"019E4C54B1B375A28970B605CA9B03C3"

instanceId

string

obsoleto

Obsoleto: usa channelId

Ejemplo:

"019E4C54B1B375A28970B605CA9B03C3"

url

string

URL de destino de los eventos

Ejemplo:

"https://app.suempresa.com/webhooks/omni-zapi"

description

string | null

Descripción del webhook

Ejemplo:

"Webhook principal de producción"

events

string[]

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

Ejemplo:

["MESSAGE_RECEIVED", "MESSAGE_STATUS"]

status

enum<string>

Estado actual del webhook

Opciones disponibles:

ENABLED,

DISABLED

Ejemplo:

"ENABLED"

signing

boolean

Indica si la firma HMAC está habilitada

Ejemplo:

true

auth

object

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

Show child attributes

payloadFormat

enum<string>

Formato del payload entregado

Opciones disponibles:

DEFAULT,

Z_API,

CHATWOOT

Ejemplo:

"DEFAULT"

customAttributes

object

Atributos extra configurados

Ejemplo:

{}

createdAt

string<date-time>

Fecha de creación

Ejemplo:

"2025-01-15T10:30:00.000+0000"

updatedAt

string<date-time>

Fecha de la última actualización

Ejemplo:

"2025-01-15T10:30:00.000+0000"

secret

string

Secret HMAC de 64 caracteres hexadecimales: se devuelve solo cuando se habilita signing en el create o el update. Guárdalo de forma segura; después no se podrá recuperar.

Ejemplo:

"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"

Canales

Mensajes

Plantillas (WhatsApp)

Flows (WhatsApp)

Webhooks

Conceptos

Firma HMAC

Validaciones

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

​Conceptos

​Firma HMAC

​Validaciones

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Conceptos

Firma HMAC

Validaciones