Resolución de problemas: webhooks

Los webhooks conectan Yarla con tus propios sistemas: antes de la llamada (obtener contexto), durante la conversación (herramientas) y después de la conversación (reenviar resultados). Los creas como acción Petición HTTP en Asistentes → Tareas, en la tarjeta Acciones.

Cuando algo falla después de la conversación, lo más rápido es mirar en la Bandeja: abre la conversación, despliega Detalles técnicos y mira en Qué hicieron las acciones. Ahí aparecen el nombre y el resultado de cada acción, por ejemplo HTTP 200, o HTTP 500 con el principio de tu respuesta. La petición en sí y la duración no se guardan. Las acciones de antes y de durante la conversación no aparecen aquí; para esas, revisa los registros de tu endpoint. A continuación tienes los problemas más habituales.

Síntomas, causas y soluciones

Síntoma	Causa probable	Solución
Tu endpoint devuelve 401 (firma no válida)	Secreto incorrecto (sustituido), cuerpo modificado antes de la verificación o diferencia de hora	Usa el cuerpo sin procesar y el secreto actual, y admite 300 s de diferencia
Falta el contexto previo a la llamada	No es una llamada entrante, respuesta demasiado lenta (más de 3 s), sin 2xx, no es un objeto JSON	Responde en menos de 3 s con un estado 2xx y un objeto JSON
Tu endpoint no recibe ninguna petición	Acción desactivada o en otro asistente, condición no cumplida, error en la URL, endpoint no público, o Probar sin Ejecutar las acciones de verdad	Revisa Qué hicieron las acciones en la Bandeja
No se usa la respuesta de la herramienta	Falta Pista sobre la respuesta, respuesta demasiado grande o sin 2xx	Consulta Resolución de problemas: prompt y herramientas
El webhook de después de la conversación llega dos veces	Dos acciones con la misma URL, o un proxy o túnel repite la petición	Elimina la acción duplicada y filtra los duplicados por conversationId
Tiempo de espera agotado	El endpoint tarda más de 3 s (antes), 6 s (durante) u 8 s (después de la conversación)	Después de la conversación, responde primero con 2xx y procesa de forma asíncrona
Variables vacías en el cuerpo	Variable sin definir, no mencionada en la conversación o no disponible en ese momento	Define la variable en la acción o usa un parámetro
Make o n8n no recibe nada	Escenario no activo o URL del webhook cambiada	Activa el escenario y actualiza la URL
Falta la cabecera X-Yarla-Signature	La acción usa el método GET	Usa POST, PUT, PATCH o DELETE

Tu endpoint devuelve 401 porque la firma no coincide

Todas las peticiones salvo GET llevan la cabecera X-Yarla-Signature: t=<unix seconds>,v1=<hex hmac_sha256(secret, t + "." + body)>. Cuando no coincide, casi siempre se debe a una de estas tres causas.

1. Secreto incorrecto. Si en Ajustes → Conexiones, en la tarjeta Secreto de webhook, hiciste clic en Generar nuevo, el secreto anterior deja de funcionar al instante y tu endpoint debe usar el nuevo. Solo un Administrador ve esa tarjeta.
2. Cuerpo modificado. Calcula el HMAC sobre los bytes sin procesar del cuerpo tal como los recibes; un JSON analizado y vuelto a serializar produce otro hash.
3. Diferencia de hora. Compara t con tu propio reloj y admite una diferencia de 300 segundos.

Consulta Webhooks.

Falta el contexto previo a la llamada

El webhook entrante es una Petición HTTP configurada como Antes de la llamada. Solo se ejecuta en las llamadas entrantes, así que no en llamadas salientes, SMS, WhatsApp, chat web ni en Probar. Tu endpoint debe responder en un máximo de 3 segundos con un estado 2xx y un objeto JSON. Si la respuesta tarda más, no es 2xx, no es un objeto JSON válido (una lista no vale) o supera los 20.000 caracteres, la ignoramos. La llamada empieza entonces sin esos datos, y variables como {{customerName}} en el saludo y {{inboundContext.customerName}} después de la conversación quedan vacías. Para ver lo que sí llegó, mira en la Bandeja, en Detalles técnicos, en Datos buscados antes de la llamada. Consulta Webhook entrante (antes de la llamada).

Tu endpoint no recibe ninguna petición

Abre la conversación en la Bandeja, despliega Detalles técnicos y mira en Qué hicieron las acciones. Esta lista muestra las acciones de después de la conversación y se rellena cuando la conversación ha terminado.

• La acción no aparece. Está desactivada, pertenece a otro asistente o no se ejecuta Después de la conversación, o la conversación sigue en curso. Una conversación por SMS, WhatsApp o chat web sigue abierta hasta que el asistente la cierra, alguien hace clic en Terminar conversación o pasa un tiempo sin actividad: en el chat web, el Tiempo de inactividad (60 minutos por defecto); en SMS y WhatsApp, 6 horas; y con tu equipo, solo 18 horas después del último mensaje, nunca mientras el cliente espera una respuesta.
• skipped: condition not met. No se cumplió la condición de ¿Con qué condición debe ejecutarse después de la conversación?. Lo mismo ocurre si el cliente no dijo nada, salvo que ese campo esté vacío.
• Un error como url host did not resolve, url host is not allowed o url address is not allowed. La URL es incorrecta o el endpoint no es accesible públicamente: localhost y las direcciones internas no funcionan. Mientras desarrollas, usa un túnel hacia tu equipo local.
• HTTP con un código de estado. La petición salió y hubo respuesta. Sigue en los registros de tu endpoint.

Una acción configurada como Durante la conversación solo se ejecuta cuando el asistente la usa, y lo decide con lo que escribiste en ¿Cuándo debe usar esto el asistente?. En Probar, con Llamar y Chatear, tu endpoint solo recibe algo si Ejecutar las acciones de verdad está activado, y esas conversaciones no aparecen en la Bandeja. Una Llamada real es una conversación real: las acciones se ejecutan de verdad y la conversación sí aparece en la Bandeja.

No se usa la respuesta de la herramienta

Si tu endpoint responde bien pero el asistente no hace nada con la respuesta, el problema está en Pista sobre la respuesta o en el tamaño de la respuesta: el asistente lee como máximo 6.000 caracteres. Si tu endpoint no devuelve un 2xx, el asistente solo recibe el código de estado. Consulta Resolución de problemas: prompt y herramientas y Webhook durante la llamada.

El webhook de después de la conversación llega dos veces

No repetimos las peticiones automáticamente, y una acción de después de la conversación se ejecuta una sola vez por conversación; no se puede volver a ejecutar a mano. Si aun así recibes algo dos veces, el asistente tiene dos acciones con la misma URL (por ejemplo, después de Duplicar) o algo entre nosotros y tu endpoint repite la petición, como un proxy o un túnel. Haz que tu procesamiento sea idempotente filtrando los duplicados por conversationId. Va en el cuerpo predeterminado; si usas tu propia Plantilla del cuerpo, añade {{conversationId}}. Consulta Webhook después de la llamada.

Tiempo de espera agotado

No esperamos a tu endpoint de forma indefinida, y no puedes cambiar cuánto tiempo: 3 segundos antes de la llamada, 6 segundos durante la conversación y 8 segundos después de la conversación. Pasado ese tiempo la petición se cancela y no se reintenta.

• Antes de la llamada: la llamada empieza sin esos datos.
• Durante la conversación: el asistente no recibe una respuesta útil. En una llamada no recibe ninguna respuesta a su petición, así que quien llama puede oír silencio. Cada segundo cuenta y el asistente necesita los datos, así que responde lo más rápido posible.
• Después de la conversación: la acción aparece con un error en Qué hicieron las acciones. Por eso, responde de inmediato con un estado 2xx y procesa los datos después de forma asíncrona (cola, tarea en segundo plano).

Las variables están vacías en el cuerpo

Las variables disponibles dependen del momento. Un nombre desconocido o mal escrito queda vacío.

• Antes de la llamada: fromNumber, toNumber, personNumber, agentNumber, company.name, company.website, company.phone, company.email y company.address.
• Durante la conversación: lo que el asistente rellena en Parámetros que rellena el asistente, más los datos indicados al inicio (campaña o API). Las variables integradas como {{personNumber}} quedan vacías aquí; conviértelas en un parámetro.
• Después de la conversación: todas las variables integradas, como summary y personNumber, y tus variables personalizadas.

Una variable personalizada se define en una acción que se ejecuta Después de la conversación, en Variables personalizadas que extraer. Solo llega rellena si esa acción está activada, la descripción es clara y el dato salió en la conversación. Si el cliente no dijo nada, summary y tus variables personalizadas también quedan vacías. company.address queda vacía si tu empresa no comparte su dirección con los clientes. Consulta Acciones.

Make o n8n no recibe nada

Un escenario de Make o un flujo de n8n solo escucha cuando está activo; el modo de prueba captura una sola petición. Comprueba también que la URL del webhook no haya cambiado al volver a crear el módulo y pega la URL actual en la acción. Consulta Make y n8n.

Falta la cabecera X-Yarla-Signature

Una petición GET no lleva cuerpo y no se firma. Todos los demás métodos llevan la cabecera sin que tengas que configurar nada: cada empresa ya tiene un secreto de webhook. Si quieres comprobar la firma, pon Método en POST, PUT, PATCH o DELETE. El secreto está en Ajustes → Conexiones, en la tarjeta Secreto de webhook.

¿Sigues con problemas?

¿Tu problema no aparece aquí o la solución no ha funcionado? Avísanos mediante Informar de un problema e indica el conversationId, la hora y el código de estado que devolvió tu endpoint.

Artículos relacionados

• Webhooks
• Webhook entrante (antes de la llamada)
• Webhook después de la llamada
• Make y n8n