¿Buscas el lado entrante, el webhook de la Cloud API de Meta que entrega los
mensajes de WhatsApp a iZap? Eso es interno de la propia conexión de WhatsApp
de iZap. Lo que describe esta página es la entrega saliente de iZap a tu
endpoint.
Registra un endpoint
url debe ser https:// en el puerto estándar (443): un puerto personalizado
(p. ej., https://example.com:8443/hook) se rechaza con 422, igual que una
dirección privada o de loopback. Puedes dejar subscribed_events como []
para recibir todos los eventos del catálogo, incluidos los que se agreguen más
adelante.
La respuesta es el único lugar donde se muestra completo el secreto de firma:
signing_secret de inmediato: no hay ningún endpoint para volver a
leerlo. Si lo pierdes, rótalo para obtener uno nuevo.
Registrar un endpoint requiere un plan que incluya webhooks de eventos. Sin
él, la llamada devuelve
403 con code: "plan_limit_event_webhooks".Un agente conectado al MCP de iZap hace lo mismo con
create_webhook_subscription, revisa el estado de las entregas con
list_integrations y elimina una suscripción con delete_webhook_subscription.
Por MCP los eventos deben elegirse explícitamente; no existe la opción de lista
vacía.Catálogo de eventos
El catálogo se versiona solo por adición: una vez publicados, los payloads de
los eventos existentes no cambian de forma, así que interpretar el
message.received de hoy sigue siendo seguro a medida que se agregan nuevos
tipos de eventos.
Payload
conversation.created
contact.phone es null para un visitante del chat del sitio web, que no tiene teléfono.
En este evento conversation_id siempre es igual a chat.id, porque se dispara para el chat que inicia la conversación. Los chats siguientes de la misma conversación, como la renovación de la sesión de 24 horas, conservan ese conversation_id y reciben su propio chat_id.
message.status_updated
error_code y error_reason solo vienen para estados de fallo (failed o undelivered).
El cuerpo se serializa con las claves ordenadas y sin espacios en blanco
adicionales, y esa secuencia exacta de bytes es la que se firma: verifica contra
el cuerpo bruto de la solicitud, no contra una re-serialización del JSON
interpretado.
Encabezados
Una entrega reintentada o reenviada manualmente lleva el mismo
izap-webhook-id y los mismos bytes de payload, pero un
izap-webhook-timestamp nuevo y las dos firmas recalculadas en el momento del
envío. Después de verificar izap-webhook-signature-v2, izap-webhook-id es
seguro como clave de idempotencia: v2 firma el propio id, así que una entrega
reproducida con otro id no pasa la verificación. Elimina duplicados por el id
solo después de que esa verificación sea correcta, nunca solo por la marca de
tiempo o la firma: ambas cambian en cada reintento y reenvío del mismo evento.
Verifica la firma
izap-webhook-signature-v2 es la verificación recomendada: es la única de las
dos que cubre izap-webhook-id, y eso cierra una brecha real. Un atacante que
captura una entrega puede reproducirla dentro de tu margen de tiempo con un
izap-webhook-id nuevo, y una verificación solo con v1 la sigue aceptando
porque v1 nunca firmó el id. Tampoco hay otro identificador firmado genérico en
el cuerpo al que recurrir, y eliminar duplicados por marca de tiempo + firma
tampoco ayuda: ambas se calculan de nuevo en cada reintento y reenvío del mismo
evento.
Heredado: firma v1
izap-webhook-signature (v1=<hex-hmac>) se sigue enviando en cada entrega y
no hay planes de dejar de hacerlo: las integraciones existentes siguen
funcionando sin cambios. No cubre izap-webhook-id, así que por sí sola no
puede distinguir una entrega reproducida con un id nuevo de una entrega nueva
genuina. Prefiere
izap-webhook-signature-v2 para las integraciones nuevas
y migra las existentes cuando te convenga.
Entrega y reintentos
- Tu endpoint tiene 10 segundos para responder. Cualquier respuesta
2xxcuenta como entregada. - Las respuestas
5xxy429se reintentan; cualquier otro4xxse trata como un rechazo permanente y no se reintenta. Devuelve2xxsolo cuando hayas aceptado el evento de forma duradera. - Después de 20 fallos consecutivos, el endpoint se desactiva
automáticamente (
enabled: false, conlast_errordefinido). Vuelve a activarlo cuando tu receptor esté bien de nuevo: no se recupera solo.
Gestiona un endpoint
Cada solicitud envía la empresa en el headerbusiness-id, como en el
ejemplo de registro anterior.
Rotar invalida el secreto anterior de inmediato: no hay periodo de
superposición, así que actualiza tu código de verificación con el nuevo secreto
antes de rotarlo en producción. Un reenvío reproduce los bytes originales
almacenados, así que se verifica contra el mismo payload que el primer intento.
Genera un receptor
izap-wizard webhook receiver escribe un punto de partida que implementa este
contrato por ti.Verifica con un SDK
webhooks.verify en los SDKs de Python y TypeScript comprueba una entrega
contra el cuerpo crudo de la solicitud. La CLI no
recibe webhooks; usa un SDK o un receptor generado.