Saltar al contenido principal

​
¿Qué son los webhooks?

Los webhooks son notificaciones HTTP que Omni Z-API envía a tu servidor cuando ocurre un evento, como la recepción de un mensaje, un estado de entrega o la actualización de una plantilla. En lugar de que tu sistema consulte la API periódicamente (polling), Omni Z-API te envía los eventos en el momento en que ocurren.
Cualquier secret key válida de un workspace activo puede gestionar webhooks, tanto de canal como de plantilla. No hace falta ningún rol específico en tu cuenta. Si el workspace no está activo, las llamadas de webhooks devuelven 422 con {"error": "Webhook management requires an active workspace"}.

​
Tipos de webhook

Omni Z-API tiene tres tipos de webhook. Lo que cambia entre ellos son los eventos admitidos y la forma de asociarlos; cada sección detalla sus particularidades. El resto de esta página aplica a los tres tipos.

Webhooks de canal

Reciben los eventos de un canal concreto (mensajes, entrega, conexión).

Webhooks de plantilla

Reciben los eventos de plantilla de WhatsApp, con independencia de la instancia.

Webhook predeterminado

Recibe los eventos de todos los canales del workspace que no tienen webhook propio.

​
Formatos de payload

Omni Z-API admite tres formatos de payload:
payloadFormat solo aplica a los webhooks de canal. En los webhooks de plantilla el formato es siempre DEFAULT y el campo se descarta.

​
URL del webhook

Al crear un webhook, y al cambiar la URL de uno existente, Omni Z-API comprueba la url antes de guardarla. Las reglas valen para los dos tipos de webhook. El host se rechaza cuando:
  • es una IP que no es pública: red privada, loopback, link-local (incluida la dirección de metadatos de la nube 169.254.169.254), CGNAT, multicast o un rango reservado, en IPv4 o IPv6;
  • es un nombre que resuelve a una de esas direcciones. Basta con una dirección no pública entre las que devuelve el nombre;
  • es localhost, termina en .localhost o .internal, o es un nombre sin punto, como https://servidor/webhook;
  • es una IPv4 escrita fuera de la forma habitual de cuatro números decimales, como http://2130706433/;
  • no existe en el DNS o no tiene dirección.
Si el DNS no responde a tiempo, la respuesta es 503 con {"error": "Could not verify the webhook URL now, try again"}. No se guarda nada: inténtalo de nuevo.
http se sigue aceptando, pero es preferible https: con http, el cuerpo del evento y los headers de autenticación viajan sin cifrar.
En la actualización, la url solo se comprueba cuando cambia. Un PATCH sin url, o con la misma URL ya guardada, no se rechaza por ella: un webhook antiguo cuya URL hoy se rechazaría puede seguir deshabilitándose, cambiando otros campos o eliminándose.

​
Autenticación del webhook

Puedes configurar cómo se autentica Omni Z-API al llamar a tu URL:

​
Firma HMAC

Para asegurarte de que las peticiones que recibes provienen realmente de Omni Z-API y no han sido manipuladas, habilita la firma HMAC indicando signing: true al crear el webhook. Cuando está habilitada:
  • Se genera un secret de 64 caracteres hexadecimales, que se devuelve una sola vez, en la creación o la actualización.
  • Cada petición enviada a tu webhook trae el header x-webhook-signature, con el formato t={unix_timestamp},v1={hmac_sha256_hex}.
  • Verificas la firma en tu servidor usando el secret que has almacenado.
La firma no es el HMAC solo del cuerpo. Se calcula sobre una cadena canónica de cinco campos, de la cual el cuerpo es el último. Consulta Firma HMAC para la cadena exacta, un ejemplo completo y código de validación listo para usar.
El secret se muestra únicamente en la respuesta de creación o de actualización con signing: true. Guárdalo de forma segura: no se puede recuperar después.