Conecta el workflow de tu CRM a un agente (URL del webhook y secreto)

Cada agente de IA de GodSetter tiene su propia URL de webhook. El workflow que apuntas a esa URL decide qué agente hace la llamada — así un mismo cliente puede usar agentes distintos para campañas distintas con solo cambiar de URL.

Esta guía conecta un workflow del CRM (por ejemplo, «nuevo lead creado») con un agente para que cada lead que procese el workflow reciba una llamada en cuestión de segundos: la primera llamada sale en el momento en que llega el lead.

Antes de empezar

• Tu CRM está conectado en Conexiones (OAuth) y la subcuenta del cliente ya se ha importado (aparece en Clientes como activa). Necesita dónde agendar: un calendario propio, o un calendario predeterminado en el agente (Identidad y enrutamiento), buscado por nombre en la subcuenta del cliente.
• El agente existe y tiene al menos un número de teléfono activo asignado (editor del agente → pestaña Números). Esto es fail-closed: un agente sin números nunca llama.
• La dirección del agente es Saliente. Un agente entrante responde devoluciones de llamada y nunca puede iniciar un ciclo de llamadas, así que no puede ser el destino de un trigger — consulta Crea agentes salientes y entrantes.

Paso 1 — Copia la URL del webhook del agente y su secreto

Abre el agente en Agentes y ve a la pestaña Datos y GHL. Ahí encontrarás:

• la URL del webhook propio del agente (…/api/webhooks/ghl-trigger/agent/<agent-id>),
• el Secreto del webhook,
• un Ejemplo de body (JSON),

cada uno con su botón de copiar. El secreto es único por agente — trátalo como una contraseña.

Paso 2 — Añade la acción webhook a tu workflow

En la subcuenta del cliente, edita el workflow que debe disparar las llamadas (por ejemplo, al crear un contacto o al cambiar de etapa del pipeline) y añade una acción Webhook:

• Método: POST
• URL: la URL del agente que has copiado
• Header: Content-Type: application/json

Paso 3 — Construye el body JSON

Campos mínimos obligatorios:

{
  "webhookSecret": "<the copied per-agent secret>",
  "locationId": "{{location.id}}",
  "contactId": "{{contact.id}}",
  "phone": "{{contact.phone}}"
}

Añadidos recomendados:

El campo timezone es opcional y se puede enviar siempre sin riesgo: un valor ausente o irreconocible se ignora, y la franja horaria cae en el huso de la subcuenta del cliente y después en el huso de reserva del agente. Se guarda en el lead, así que los reintentos y las devoluciones de llamada posteriores lo reutilizan. Detalles en Define una franja horaria por agente.

Paso 4 — Envía un lead de prueba

La comprobación más rápida está en la app. En la misma pestaña Datos & GHL, debajo de la tarjeta del webhook y de la tarjeta Etiqueta de inicio, la tarjeta Envía un lead de prueba simula un lead que llega desde el workflow: elige el cliente (solo se listan los clientes activos con dónde agendar — su propio calendario o el predeterminado del agente), introduce un teléfono que controles y pulsa Enviar lead de prueba. El lead pasa por la misma entrada que los webhooks — controles de dirección, cliente, número, consentimiento y Do-Not-Call — y después por el envío inmediato: si todo está conectado, el agente te llama en pocos segundos. Es una llamada real (coste real) sobre un lead real, que queda en Llamadas y Leads como cualquier otro. El calendario es el real del cliente; la reserva, las etiquetas y las notas se simulan: en el CRM no queda nada. La tarjeta muestra una traza de tres líneas (y, como el lead es real, una prueba sin respuesta la vuelve a marcar el plan de reintentos del agente: espera más llamadas reales a tu número salvo que bloquees el lead desde la página Leads):

• Entrada — lead aceptado, u omitido con el motivo (los mismos de la tabla de abajo);
• Envío — llamada iniciada, en cola en cabeza (todos los slots ocupados), aparcada a la apertura de la franja (fuera del horario de llamadas), o no iniciada con el motivo;
• Abrir el lead — el lead que creó la prueba.

Si el prompt activo del agente cita custom values (tokens {{cv_*}}), la tarjeta muestra también una sección Custom values del prompt con un campo por token. Rellena lo que el workflow enviaría para ese contacto: los valores llegan al lead de prueba exactamente como los customValues de un trigger real, así que la llamada habla con los mismos datos. Un campo vacío no se envía y el token queda vacío, salvo que la subcuenta del cliente tenga un custom value con ese nombre.

Después haz la comprobación real desde el CRM: dispara el workflow con un contacto de prueba (usa un teléfono que controles). Respuesta esperada:

{ "status": "enqueued", "leadId": "…" }

Dentro de tu franja horaria la llamada sale en pocos segundos; fuera de ella, el lead espera la apertura. Consulta Llamadas para ver la entrada en vivo.

Si la respuesta indica skipped

El campo reason te dice qué control de activación detuvo la llamada:

Un trigger duplicado — el mismo contacto disparado dos veces en menos de 10 minutos — recibe su propia respuesta, {"status":"duplicate"}, y simplemente se ignora: es la deduplicación integrada funcionando como debe.

Tres de estas omisiones se etiquetan además en tu CRM — no_number, no_consent y blocked (los nombres son configurables en Ajustes → Etiquetas CRM) — para que tus workflows puedan reaccionar. Las otras tres (client_inactive_or_not_found, not_configured e inbound_agent) son errores de configuración de tu lado: se informan en la respuesta y en el propio lead, pero no se escribe nada en el CRM.

Paso 5 — Detén el ciclo cuando el contacto reserve por su cuenta

Una reserva hecha durante una llamada ya detiene el ciclo automáticamente. Pero un contacto también puede reservar fuera de cualquier llamada: por el enlace del funnel o con un agente humano. Avisa a GodSetter para que las rellamadas programadas nunca marquen a alguien que ya reservó:

1. En la subcuenta del cliente, crea un segundo workflow con el disparador nativo del CRM «Customer booked appointment».
2. Añade una acción Webhook apuntando a la URL «Cita reservada (detener llamadas)» que aparece en la página Conexiones (la página también muestra el secreto del webhook de la agencia y un body de ejemplo listo para pegar).
3. Campos del body: webhookSecret (el secreto de agencia de Conexiones), locationId, contactId y opcionalmente phone.

Si todo va bien la respuesta es {"status":"stopped"}: el lead queda marcado como reservado y todas sus rellamadas/callbacks programadas se eliminan. Una respuesta not_found es benigna: ese contacto simplemente no estaba en un ciclo de llamadas.

Las otras URL de la página Conexiones

La tarjeta Webhooks entrantes de la página Conexiones lista cinco URL, y solo dos son para pegar en GoHighLevel:

• Disparador de llamada — el disparador a nivel de agencia (la URL heredada; la URL por agente del Paso 1 es la configuración recomendada).
• Cita reservada (detener llamadas) — el Paso 5 de arriba.

Las otras tres — Inbound voice, Call lifecycle y Herramientas en llamada — son webhooks de Retell, y los configura GodSetter por ti: las URL de call lifecycle y herramientas en llamada se fijan en el agente al crearlo (y se vuelven a aplicar con «Sincronizar herramientas GHL»), y la URL de inbound voice se fija en el número cuando lo registras en Retell. No hay nada que pegar: se muestran como referencia, por ejemplo para comprobar a qué host apuntan tus agentes y tus números. El Secreto del webhook solo sirve para los dos webhooks de GoHighLevel.

Regenerar el secreto

Regenera un secreto cuando pueda haberlo visto alguien que ya no debería tenerlo — un ex miembro del equipo, una captura compartida, un workflow copiado a otra cuenta. El secreto anterior deja de funcionar al instante, y solo para ese agente o para tu agencia: nada más cambia.

• El secreto de un agente — en la pestaña Datos y GHL del agente, Regenerar el secreto debajo del secreto. Autentica la URL del webhook de ese agente.
• El secreto de la agencia — en la página Conexiones, Regenerar el secreto debajo del Secreto del webhook. Autentica las dos URL de la agencia: Disparador de llamada y Cita reservada (detener llamadas).

Solo el titular de la cuenta ve el botón — ni los miembros del equipo ni el soporte de GodSetter — y pide confirmación antes: los workflows de GoHighLevel que usan el secreto actual dejan de funcionar hasta que pegues el nuevo. Desde ese momento reciben 401 (invalid secret) y no se llama a ningún lead. Después:

1. Copia el nuevo secreto: la página lo muestra enseguida.
2. En cada workflow que llama a esa URL, abre la acción Webhook y sustituye el valor de webhookSecret en el body (Pasos 3 y 5).
3. Envía una prueba (Paso 4) y comprueba que la respuesta vuelve a ser enqueued.

Las URL no cambian, ni tampoco el Agent ID y el Account ID: las acciones de workflow con marca y la etiqueta de inicio no usan el secreto y siguen funcionando. Cada regeneración queda en el registro de Auditoría como webhook.secret.rotate — nunca el secreto.

Mejor aún: las acciones de workflow con marca

Si la app del marketplace de GodSetter está instalada en la subcuenta, ambos pasos están disponibles como acciones de workflow nativas, sin URL ni JSON que pegar. Requieren esa app instalada en la subcuenta y la facturación "Workflow LC Premium Triggers & Actions" habilitada en ella; sin las dos cosas, los nodos de marca no aparecen en el constructor de workflows y el webhook genérico sigue siendo el camino.

• Iniciar ciclo de llamadas — elige la acción y pega el ID del agente (se copia desde la pestaña Datos y GHL del agente). El teléfono, el nombre y los custom fields del contacto se obtienen automáticamente — cada token {{cv_contact_*}} del prompt se resuelve sin ningún mapeo.
• Cita reservada (detener llamadas) — elige la acción y pega tu ID de cuenta (se copia desde la página Conexiones).

El webhook genérico sigue totalmente soportado; las acciones hacen lo mismo con menos configuración. El consentimiento funciona igual: la acción de inicio tiene un campo opcional Consent proof (prueba de consentimiento) — pega el mismo objeto que el webhook envía como consentProof, por ejemplo {"formId": "…", "submittedAt": "…"}, mapeando los valores de tu formulario de opt-in. Con el modo estricto activo, un campo vacío o no válido hace que el lead se omita como no_consent. (Los custom fields del contacto y los valores ya guardados por triggers webhook anteriores se aplican automáticamente.)

Sin workflow: la etiqueta de inicio

¿Prefieres no tocar los workflows? Dale al agente una etiqueta de inicio: en la pestaña Datos y GHL del agente rellena Etiqueta de inicio (p. ej. llamar-con-ia) y guarda. Desde ese momento, añadir esa etiqueta a un contacto en el CRM inicia el ciclo de llamadas de este agente para ese contacto — es el reflejo de la etiqueta de desconexión. Requiere la app del marketplace de GodSetter instalada (así es como GodSetter se entera de los cambios de etiquetas) y la subcuenta del contacto importada como cliente.

• Siguen valiendo todos los controles de arriba: un agente inbound o desactivado, un cliente sin dónde reservar, sin número, sin consentimiento en modo estricto o un lead en Do-Not-Call significan que no hay llamada.
• Una etiqueta, un agente: dos agentes de la misma agencia no pueden compartir la etiqueta de inicio, y no se pueden usar la etiqueta de desconexión ni una etiqueta que GodSetter escribe por su cuenta.
• La etiqueta inicia el ciclo una vez mientras siga en el contacto, por mucho que cambien sus otras etiquetas (incluidas las de resultado que escribe GodSetter). Para volver a empezar, quita la etiqueta y vuelve a ponerla.
• No empieza nada si el contacto también lleva la etiqueta de desconexión (el contacto sale de GodSetter) o si el ciclo del lead ya terminó con cita reservada o no interesado.
• A diferencia del webhook y de la acción de inicio, la etiqueta no transporta prueba de consentimiento ni custom values: con el modo estricto activo, para los clientes que requieren consentimiento usa uno de esos dos (con la etiqueta el lead se saltaría como no_consent).

Volver a contactar un lead que ya pasó por el workflow

Un workflow que arranca con "Etiqueta añadida al contacto" no vuelve a ejecutarse si quitas la etiqueta y la vuelves a poner en pocos segundos: GoHighLevel lo trata como el mismo evento y lo descarta, así que no empieza ninguna llamada nueva. Para volver a llamar a ese contacto:

• espera unos minutos — hasta que el workflow muestre terminado el paso anterior del contacto — y luego quita la etiqueta y vuelve a ponerla; o
• usa una etiqueta dedicada al nuevo contacto (por ejemplo volver-a-llamar) con su propio workflow y la misma acción webhook, para que el nuevo disparo nunca se confunda con el primero.

En ambos casos el nuevo disparo reinicia el ciclo de llamadas (ver abajo).

Conviene saber

• Una URL por agente. Para dirigir una campaña a otro agente, duplica el workflow y cambia la URL y el secreto — no hay que tocar nada en GodSetter.
• Un trigger nuevo reinicia el ciclo. Volver a disparar el workflow para un contacto que GodSetter ya conoce pone el contador de intentos a cero y descarta los reintentos que siguieran aparcados para ese lead, así que el plan empieza por la llamada n.º 1 en lugar de retomarse a mitad. Una devolución de llamada que pidió el lead sí se conserva.
• El webhook heredado a nivel de agencia (sin /agent/) sigue funcionando y usa el agente predeterminado del cliente, pero la URL por agente es la configuración recomendada — y responde {"status":"skipped","reason":"no_template"} cuando el cliente no tiene agente predeterminado. Ese predeterminado es el campo Agent Template de la ficha del cliente (Gestiona tus clientes).
• Si el workflow se dispara con la franja horaria de llamadas cerrada, el lead espera en la cola y se llama cuando la franja se reabre.