Webhooks sin miedo: cómo tu agente le habla al resto del mundo

---

Si nunca has trabajado con webhooks, la palabra suena a algo que sólo la gente de desarrollo entiende. Spoiler: no. Una vez que pillas la idea, no se puede desver. Y abre la puerta a que tu agente no sólo atienda llamadas, sino que le avise a todos tus sistemas lo que pasó en cada una. Vamos a desmitificarlo con una analogía.

​

La analogía del mesero

Imagina que tu agente es un mesero en un restaurante. Cada vez que termina una mesa, podría: A) Anotarlo en un cuaderno que sólo él lee. B) Gritar a la cocina cada vez que pasa algo importante: “¡mesa 5, pidieron la cuenta!”, “¡mesa 7, se fueron!”. La opción A es como tener un agente sin webhooks: los datos se quedan adentro y alguien tiene que ir a leerlos. La opción B es el webhook. Un grito estructurado que dice “oye mundo exterior, acaba de pasar algo, aquí está el detalle”. Ese grito va por internet, llega a una URL que tú definas, y tus sistemas (CRM, correo, Slack, lo que quieras) pueden escucharlo y reaccionar.

​

Dos partes, no una

La gente junta “conectar un webhook” con “usarlo” y se confunde. En realidad son dos pasos distintos:

1. Crear la conexión: le das al sistema una URL de destino. Es como registrar el número de teléfono al que quieres recibir SMS.
2. Suscribirte a eventos: le dices QUÉ avisos quieres recibir. Es como elegir si quieres que te avisen cuando llega un paquete, cuando hay una promoción, o ambas.

Nada te sirve uno sin el otro. Una conexión sin suscripciones es un teléfono que nadie va a marcar. Una suscripción sin conexión no tiene a dónde mandarse.

​

Parte 1: Crear la conexión

​

Dónde se hace

En la barra lateral izquierda de Agents Studio hay una sección Webhooks (suele aparecer bajo “Recursos”, cerca de “Claves API” y “Documentación”). Dale clic. Verás la lista de webhooks ya creados (si hay) y, arriba a la derecha, un botón morado + NUEVO WEBHOOK.

​

Los cinco campos que vas a llenar

1. URL del endpoint Es la dirección a la que Agents Studio va a mandar los avisos. Tiene que:

• Empezar con https:// (no http://; seguridad).
• Apuntar a algún servicio que pueda recibir datos por internet.

Si todavía no sabes qué URL poner, ahí es donde entran n8n o Make (veremos esto en los próximos dos posts de la serie). Ellos te dan una URL “mágica” a la que puedes mandarle todo. 2. Descripción Opcional pero muy recomendable. Ponle algo como “Webhook para campaña Bulk100 – envía resultados a nuestro CRM”. Tu yo del futuro te lo va a agradecer cuando tengas 30 webhooks. 3. Método HTTP Dos opciones: POST o GET.

• POST: cuando Agents Studio te ENVÍA información (lo que vas a querer el 99% del tiempo).
• GET: cuando tu sistema quiere LEER información (menos común en este escenario).

Si no sabes, pon POST. Así siempre. 4. Activar inmediatamente Un interruptor que deja el webhook listo para funcionar desde ya. Déjalo prendido. 5. Seguridad — Secret Key Esta es la clave que usa Agents Studio para firmar cada aviso que manda. Tu sistema del otro lado puede usarla para verificar: “ok, este aviso viene de verdad de Agents Studio y no de alguien haciéndose pasar por él”. Mínimo 16 caracteres. Ponle algo largo y aleatorio; hay generadores gratuitos en internet que te los dan con un clic. Guarda la Secret Key en un lugar seguro. Después sólo la puedes consultar con un botón “Ver secreto” que requiere permisos. No la pierdas.

​

Headers personalizados (opcional)

Algunos servicios de destino piden que cada mensaje lleve una cabecera extra (por ejemplo, Authorization: Bearer xxxx). Eso se configura aquí. Si no te dijeron que lo uses, ignóralo.

​

Darle a “Crear”

Y listo. La conexión existe. Pero todavía no hace nada, porque no está suscrita a ningún evento.

​

Parte 2: Suscribirte a eventos

Una vez creada la conexión, entras a los detalles del webhook. Vas a ver una sección que dice Suscripciones a Eventos con un botón + AGREGAR EVENTO. Al darle clic, te sale una lista con los eventos disponibles. Los más importantes son:

​

call.callStarted — Llamada iniciada

El banderazo de salida. Se dispara en el segundo exacto en el que el cliente contesta. Dice:

• Qué agente está atendiendo.
• Desde qué stage empezó.
• La hora exacta.

Útil para: marcar el CRM como “en llamada”, empezar un cronómetro, mandar una notificación al equipo.

​

call.callEnded — Llamada finalizada

Se dispara cuando la llamada termina, independientemente del resultado. Dice:

• Duración total.
• Por qué terminó.
• Datos básicos.

Útil para: actualizar el estado del contacto a “contactado”, generar reportes de actividad.

​

call.transferBridged — Transferencia exitosa

Se dispara cuando el agente transfiere a un humano y la conexión se logró establecer. Dice:

• A qué número se transfirió.
• Si el puente funcionó.
• Enlace al transcript hasta ese momento.

Útil para: avisar al equipo humano que les va a llegar una llamada, pre-cargar contexto en la pantalla del operador.

​

call.callAnalyzed — Llamada analizada

Se dispara unos segundos después de que la llamada termina, cuando Speech Analytics ya procesó el audio. Dice:

• Si el objetivo se cumplió (goal.achieved: true/false).
• Por qué (o por qué no).
• Todas las variables de salida rellenadas.
• Resumen de la conversación.
• Código y subcódigo de resultado.

Este es el que vas a querer casi siempre. Es el reporte definitivo de la llamada, el que tiene la “inteligencia”.

​

¿Cómo elegir a qué eventos suscribirte?

Regla simple:

• Quiero reaccionar al inicio de la llamada → call.callStarted.
• Quiero saber cuando termine, rápido → call.callEnded.
• Quiero actuar después del resultado completo → call.callAnalyzed.
• Transfiero a humanos y necesito coordinar → call.transferBridged.

Lo más común: la gente se suscribe a call.callAnalyzed y ya. Con eso tienen todo lo que necesitan. Puedes suscribirte a varios eventos al mismo tiempo. Cada uno dispara un aviso independiente.

​

El panel de entregas: tu mejor amigo debugueando

Dentro del webhook, hay una sección Entregas (historial). Muestra cada aviso que se envió, con:

• Fecha y hora.
• Evento que disparó.
• Código HTTP de respuesta (200 = todo bien; 4xx o 5xx = algo falló).
• Intentos (si la primera vez falló, el sistema reintenta).

Si algo no está llegando a tu sistema, abre este panel antes de entrar en pánico. El 80% de las veces el problema se ve aquí: la URL estaba mal, o tu sistema devolvió un error.

​

Los contadores de arriba

En la vista del webhook verás tres números grandes:

• Exitosas — cuántos avisos llegaron bien.
• Fallidas — cuántos no se pudieron entregar.
• Última — la hora del aviso más reciente.

Si ves un número de fallidas creciendo, algo hay que revisar.

​

Lo más importante: NO uses datos falsos

He visto equipos configurar webhooks a URLs como https://example.com, darle guardar, y pensar “ya quedó”. No. Esa URL no existe. Cuando se dispare el evento, va a fallar y listo. Antes de darle “crear” a un webhook, asegúrate de que la URL de destino está viva y lista para recibir. Lo más fácil: usa una herramienta tipo n8n o Make que te genera URLs “para pruebas” en un clic. Lo veremos en los siguientes dos posts.

---

Con la teoría cubierta, en el próximo post hacemos lo bonito: capturar un webhook en n8n y disparar automáticamente un correo electrónico. Todo sin escribir una sola línea de código.