Saltar al contenido principal
Los webhooks salientes envían eventos a una URL que tú controlas, así no tienes que consultar la API REST en busca de actividad nueva. Registra un endpoint una vez e iZap le envía cada evento suscrito en el momento en que ocurre. Con el Analytics MCP y la API REST eres tú quien llama a iZap; aquí es iZap quien te llama a ti.
¿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:
Guarda 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.
Lee el cuerpo como bytes brutos antes de cualquier interpretación de JSON que tu framework haga automáticamente: la mayoría de los frameworks almacenan y vuelven a codificar el cuerpo interpretado, y eso ya no coincide con lo que se firmó.

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 2xx cuenta como entregada.
  • Las respuestas 5xx y 429 se reintentan; cualquier otro 4xx se trata como un rechazo permanente y no se reintenta. Devuelve 2xx solo cuando hayas aceptado el evento de forma duradera.
  • Después de 20 fallos consecutivos, el endpoint se desactiva automáticamente (enabled: false, con last_error definido). 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 header business-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.