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"
}Crear webhook
Registra un endpoint de webhook en un canal
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, 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
Sisigning: 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. Calcula el HMAC-SHA256 sobre el body recibido usando el secret y compáralo con el header de firma que envía .
channelId se obtiene a través del endpoint Crear canal.Autorizaciones
Secret Key generada en el panel de Seguridad de Omni Z-API
Parámetros de ruta
ID del canal
"019E4C54B1B375A28970B605CA9B03C3"
Cuerpo
URL de destino de los eventos (máx. 2048 caracteres)
"https://app.suempresa.com/webhooks/omni-zapi"
Tipos de evento que se van a recibir. Es obligatorio al menos uno.
MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK ["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
Descripción opcional del webhook
"Webhook principal de producción"
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.
true
Configura cómo se autentica Omni Z-API al llamar a tu URL
Show child attributes
Show child attributes
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.
DEFAULT, Z_API, CHATWOOT "DEFAULT"
Atributos extra
{}
Respuesta
Webhook creado correctamente. El campo secret se devuelve solo en esta respuesta cuando signing es true; guárdalo de forma segura.
ID único del webhook
"A1B2C3D4E5F6789012345678901234AB"
ID del canal al que pertenece el webhook
"019E4C54B1B375A28970B605CA9B03C3"
Obsoleto: usa channelId
"019E4C54B1B375A28970B605CA9B03C3"
URL de destino de los eventos
"https://app.suempresa.com/webhooks/omni-zapi"
Descripción del webhook
"Webhook principal de producción"
Tipos de evento configurados
["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
Estado actual del webhook
ENABLED, DISABLED "ENABLED"
Indica si la firma HMAC está habilitada
true
Resumen de la autenticación configurada: las credenciales no se devuelven por seguridad
Show child attributes
Show child attributes
Formato del payload entregado
DEFAULT, Z_API, CHATWOOT "DEFAULT"
Atributos extra configurados
{}
Fecha de creación
"2025-01-15T10:30:00.000+0000"
Fecha de la última actualización
"2025-01-15T10:30:00.000+0000"
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.
"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"