Webhooks: enviar eventos a tu sistema externo

Los webhooks permiten que iAnswer notifique a un sistema externo (tu CRM corporativo, tu ERP, una hoja de Google, un Zapier) cuando algo importante pasa dentro de la plataforma. Es la forma estándar de integración con otras herramientas sin necesidad de polling constante.

Eventos que puedes enviar

• contact.created: se creó un contacto nuevo.

• contact.stage_changed: un contacto cambió de etapa del funnel.

• conversation.handed_over: el bot escaló una conversación a humano.

• appointment.created: se agendó una cita.

• appointment.cancelled: se canceló una cita.

• order.created: entró una orden (restaurantes).

• order.status_changed: cambió el estado de una orden.

• property.viewed: alguien consultó una propiedad pública.

• payment.received: Stripe confirmó un pago.

• opt_out.received: un contacto solicitó opt-out.

Configurar un webhook

1. Como admin, ve a Panel Admin → Webhooks.

2. Haz clic en "Nuevo webhook".

3. Pega la URL del endpoint que va a recibir los eventos (debe ser HTTPS).

4. Selecciona los eventos a los que quieres suscribirte.

5. Define un secret para validación (lo usaremos para firmar los payloads con HMAC).

6. Guarda.

Formato del payload

Cada evento llega como POST con body JSON:

{ "event": "contact.created", "timestamp": "2026-06-28T12:00:00Z", "data": { ... } }

El header X-iAnswer-Signature contiene la firma HMAC-SHA256 del body usando tu secret. Tu endpoint debe validar esa firma antes de procesar, para garantizar que el evento realmente viene de iAnswer y no de un tercero.

Reintentos

Si tu endpoint no responde con un código HTTP 2xx en menos de 10 segundos, el sistema considera la entrega fallida y reintenta con backoff exponencial:

• Primer reintento: a los 5 segundos.

• Segundo reintento: a los 30 segundos.

• Tercer reintento: a los 2 minutos.

Después de los 3 reintentos fallidos, el webhook se marca como failed en el panel y se envía un email al admin de la cuenta para que revise. El evento queda registrado en el log de webhooks para que puedas verlo manualmente y, si quieres, dispararlo de nuevo desde la interfaz.

Troubleshooting

Si los eventos no están llegando a tu endpoint:

• Verifica que la URL sea pública (no localhost ni redes internas).

• Confirma que el certificado HTTPS sea válido (no autofirmado, no caducado).

• Revisa el log de webhooks en Panel Admin → Webhooks → Histórico, donde puedes ver código de respuesta y body devuelto por tu endpoint en cada intento.

• Asegúrate de que tu endpoint responde rápido (idealmente menos de 1 segundo). Si necesitas hacer trabajo pesado, regresa 200 OK de inmediato y procesa en background.

• Si la firma HMAC no valida, revisa que el secret guardado en iAnswer coincida exactamente con el que usa tu endpoint para verificar.