Webhook entrante (antes de la llamada)

Con el webhook entrante llamamos a tu servidor en cuanto entra una llamada, antes del saludo. El asistente usa el JSON que devuelves durante esa conversación, por ejemplo para saludar a quien llama por su nombre o mencionar una factura pendiente.

¿Cuándo se ejecuta?

• Llamadas entrantes: en cada llamada que atiende el asistente, antes del saludo, también con números desconocidos. Quien llama espera hasta que tu servidor responde.
• SMS, WhatsApp y chat web: nunca.
• Llamadas salientes: nunca. En ese caso pasas tú las variables a través de la campaña o de la API; consulta Llamadas salientes.
• Probar: nunca. Así que prueba el webhook con una llamada real.

Una llamada rechazada, por ejemplo de un contacto bloqueado, no ejecuta el webhook. Una condición en la acción no tiene efecto aquí: si la acción está activada, se ejecuta en cada llamada a ese asistente.

La petición

Con la Plantilla del cuerpo vacía enviamos un POST con este cuerpo JSON y la cabecera X-Yarla-Signature (consulta Webhooks para comprobar la firma). El punto forma parte literal del nombre del campo.

{
  "fromNumber": "+31612345678",
  "toNumber": "+31201234567",
  "personNumber": "+31612345678",
  "agentNumber": "+31201234567",
  "company.name": "Fontanería Jansen",
  "company.website": "https://www.ejemplo.es",
  "company.phone": "+31201234567",
  "company.email": "info@ejemplo.es",
  "company.address": ""
}

Campo	Significado
personNumber, fromNumber	El número de quien llama (E.164). Los dos campos tienen el mismo valor.
agentNumber, toNumber	Tu número al que se ha llamado. Los dos campos tienen el mismo valor.
company.name	El nombre de tu empresa.
company.website, company.phone, company.email	Tu sitio web y el teléfono y el correo para clientes. Vacíos si no los has rellenado.
company.address	Tu dirección, solo si Compartir esta dirección con los clientes está activado. Si no, vacío.

Otros datos, como el id de la conversación o el canal, no se envían. En tu propia Plantilla del cuerpo solo puedes usar estos campos, por ejemplo {{personNumber}} o {{company.name}}; otras variables como {{conversationId}} quedan vacías. Una petición GET no lleva cuerpo y no se firma, así que mejor deja el método en POST.

La Clave de autorización de la acción no se envía con esta petición. Si tu endpoint espera una clave, ponla en Cabeceras, por ejemplo X-Api-Key: …. Ese valor queda legible en el formulario.

La respuesta

Responde con un estado 2xx, por ejemplo 200, y un objeto JSON, mejor si es plano: claves con cadenas de texto, números o booleanos.

{
  "customerName": "Jan de Vries",
  "customerId": "C-1042",
  "openInvoice": true,
  "lastVisit": "2026-06-12"
}

Reglas:

• Un objeto vacío {}, un estado fuera de 2xx, una respuesta que no sea un objeto JSON (como una lista o texto sin formato) o un tiempo de espera agotado (3 segundos) significa sin contexto. El asistente empieza sin él; la conversación siempre continúa. Una petición fallida no se reintenta.
• Los objetos anidados siguen anidados: { "customer": { "name": "Jan" } } lo usas como {{customer.name}}.
• No uses listas. Convierte tú la lista en un texto legible, por ejemplo "openInvoices": "2 facturas, total 340 €".
• Que sea breve: unos pocos campos. Todo lo que devuelves pasa a formar parte del prompt. Una respuesta de más de 20.000 caracteres se corta y entonces ya no se puede leer.
• Si tienes varias acciones antes de la llamada, se ejecutan una tras otra y sus respuestas se combinan. Con el mismo nombre de campo vale la última respuesta. Cada acción dispone de 3 segundos, así que quien llama espera más.

Usar el contexto

En el saludo. Ahí los campos están disponibles directamente con su propio nombre, por ejemplo {{customerName}}. La forma larga {{inboundContext.customerName}} queda vacía ahí.

En el prompt. El asistente recibe todos los campos como contexto durante la llamada sin que hagas nada. Como variables no funcionan en el prompt: {{customerName}} queda vacío ahí. Así que menciona el campo por su nombre, como en el ejemplo de Configurarlo.

En acciones durante la conversación. Una Petición HTTP o una acción de Google Sheets durante la conversación no puede usar estos campos como variables. Si necesitas ese valor ahí, conviértelo en un parámetro en Parámetros que rellena el asistente.

En acciones después de la conversación. En correo, SMS, Petición HTTP y Google Sheets usa siempre la forma {{inboundContext.customerName}}. En el cuerpo predeterminado del webhook después de la llamada todos los campos están bajo inboundContext.

En la Bandeja. En la conversación ves los campos devueltos en Detalles técnicos, en Datos buscados antes de la llamada, para comprobar qué sabía el asistente. Una petición fallida solo aparece ahí como {}: Qué hicieron las acciones solo muestra las acciones después de la conversación.

Si falta un campo, la variable queda vacía. Como el saludo es un texto fijo, "Buenas tardes, {{customerName}}" suena raro cuando no hay nombre. Por eso es mejor dejar el uso del nombre a una regla del prompt.

Configurarlo

1. Abre el asistente en Asistentes, ve a la pestaña Tareas, abre la tarjeta Acciones y haz clic en Añadir nuevo. Para ello necesitas el rol Editor o Administrador.
2. Elige Petición HTTP.
3. Pon un Nombre a la acción y en Cuándo elige Antes de la llamada.
4. En URL introduce la dirección de tu endpoint, preferiblemente con https://. Las direcciones internas y privadas se rechazan. Deja el Método en POST y la Plantilla del cuerpo vacía para enviar la petición estándar que aparece arriba.
5. La acción se guarda automáticamente en cuanto tiene un nombre y una dirección web válida. Después haz clic en Cerrar.
6. Llama al número del asistente y comprueba en la Bandeja que Detalles técnicos muestra los campos esperados.

Después, en la pestaña Instrucciones, añade una regla en Reglas importantes (en Modo avanzado: en Instrucción completa), por ejemplo:

Si customerName es conocido, llama a la persona por su nombre y pregunta si se trata de la dirección que ya conocemos.
Si customerName está vacío o falta, pregunta primero el nombre.
Si openInvoice es verdadero, menciona con amabilidad la factura pendiente antes de reservar una cita nueva.

Consejos

• Responde en menos de 3 segundos. Busca por número de teléfono con un índice o una caché, y no hagas más de una búsqueda por petición.
• ¿Número desconocido? Devuelve {} con estado 200. Un estado de error tiene el mismo efecto.
• Nunca devuelvas secretos ni datos sensibles como contraseñas, datos bancarios o números de identificación. Todo lo que devuelves entra en el prompt y se ve en la Bandeja y a través de la API.
• Normaliza el número por tu parte: personNumber está en E.164 (+31612345678), tu CRM quizá no. Con un número oculto, el campo puede estar vacío o contener algo que no es un número de teléfono.
• ¿Sin servidor propio? Con Make o n8n puedes buscar un contacto en HubSpot o Google Sheets y devolver la respuesta sin programar; consulta Make y n8n.

Artículos relacionados

• Petición HTTP
• Escribir un buen prompt
• Make y n8n
• Webhooks