curl --request POST \
--url https://api.omni.z-api.io/v1/default-instance-webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://app.suempresa.com/webhooks/omni-zapi",
"description": "Eventos de todos los canales",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
]
}
'{
"id": "5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B",
"channelId": null,
"instanceId": null,
"url": "https://app.suempresa.com/webhooks/omni-zapi",
"description": "Eventos de todos los canales",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
],
"status": "ENABLED",
"signing": false,
"secret": null,
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2026-10-22T15:00:00.000+00:00",
"updatedAt": "2026-10-22T15:00:00.000+00:00"
}Crear webhook predeterminado
Registra un webhook que recibe los eventos de todos los canales del workspace
curl --request POST \
--url https://api.omni.z-api.io/v1/default-instance-webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://app.suempresa.com/webhooks/omni-zapi",
"description": "Eventos de todos los canales",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
]
}
'{
"id": "5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B",
"channelId": null,
"instanceId": null,
"url": "https://app.suempresa.com/webhooks/omni-zapi",
"description": "Eventos de todos los canales",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
],
"status": "ENABLED",
"signing": false,
"secret": null,
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2026-10-22T15:00:00.000+00:00",
"updatedAt": "2026-10-22T15:00:00.000+00:00"
}Conceptos
Crea un webhook predeterminado en el workspace de la secret key. A partir de la creación, Omni Z-API envía a la URL indicada los eventos suscritos de todo canal del workspace que no tiene un webhook propio activo. Consulta quién recibe cada evento en Webhook predeterminado del workspace. El campoevents admite solo eventos de canal (MESSAGE_RECEIVED, MESSAGE_STATUS, CONNECTED, etc.). Un evento de plantilla devuelve 422.
Formato
payloadFormat admite DEFAULT (si se omite) y Z_API. CHATWOOT devuelve 422: Chatwoot se configura en el webhook de cada canal.
Límite
Cada workspace tiene hasta 5 webhooks predeterminados, contando los habilitados y los deshabilitados. El sexto devuelve422 con Default instance webhook limit reached (5).
Firma HMAC
Sisigning: 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.
http o https, de hasta 2048 caracteres, y su host debe resolver solo a direcciones públicas.Autorizaciones
Secret Key generada en el panel de Seguridad de Omni Z-API
Cuerpo
Cuerpo de la creación
URL de destino de los eventos. URL absoluta http o https, de hasta 2048 caracteres, cuyo host resuelve solo a direcciones públicas.
"https://app.suempresa.com/webhooks/omni-zapi"
Eventos de canal que recibe el webhook. Al menos uno. El nombre se acepta en mayúsculas o minúsculas.
1MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
]
Descripción opcional del webhook
"Eventos de todos los canales"
true genera un secret de 64 caracteres hexadecimales para la firma HMAC, devuelto solo en esta respuesta.
Tipo de autenticación (forma plana). Alternativa al objeto auth.
NONE, BEARER, API_KEY, BASIC, CUSTOM_HEADER Credencial para BEARER (forma plana)
Credencial para API_KEY (forma plana)
Cómo se autentica Omni Z-API al llamar a tu URL
Show child attributes
Show child attributes
DEFAULT (el que se usa si se omite) o Z_API. CHATWOOT se rechaza con 422: configura Chatwoot en el webhook del canal. Cualquier otro valor se trata como DEFAULT.
DEFAULT, Z_API Mapa libre de atributos extra
Respuesta
Webhook predeterminado creado. channelId e instanceId vienen como null. El secret viene relleno solo cuando la petición trae signing: true, y es la única vez que aparece.
ID del webhook predeterminado
"5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B"
Siempre null: el webhook predeterminado no pertenece a un canal
null
Siempre null. Campo heredado, mantenido por compatibilidad
null
"https://app.suempresa.com/webhooks/omni-zapi"
"Eventos de todos los canales"
MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK ENABLED o DISABLED
ENABLED, DISABLED true cuando la firma HMAC está activa
Secreto de la firma HMAC. Viene relleno solo en la respuesta que lo generó (signing: true); en las demás, null.
Resumen de la autenticación configurada. Las credenciales no se devuelven.
Show child attributes
Show child attributes
DEFAULT, Z_API Fecha de creación
Fecha de la última modificación