Webhooks #

Los webhooks permiten que Your AI Connector notifique automáticamente a sus otras herramientas empresariales siempre que ocurra algo importante: la creación de un nuevo contacto, la reserva de una cita o la recepción de un mensaje. En lugar de comprobar manualmente si hay actualizaciones, sus sistemas conectados reciben una notificación instantánea en el momento en que sucede algo.

¿Qué son los webhooks? #

Piense en un webhook como un mensaje de texto automático entre dos aplicaciones. Cuando ocurre algo en Your AI Connector (como el registro de un nuevo contacto), la plataforma envía instantáneamente una notificación a otro sistema de su elección. Usted proporciona una dirección web (llamada “URL de webhook”) a la que deben enviarse estas notificaciones; normalmente, esta la proporciona su CRM, plataforma de automatización o desarrollador.

Los webhooks solo envían datos FUERA de Your AI Connector. Un webhook es una vía de sentido único desde Your AI Connector hacia sus otras herramientas. No existe una URL de webhook que envíe clientes potenciales, contactos o mensajes HACIA la plataforma. Para introducir un nuevo cliente potencial (desde un formulario web, su CRM o GoHighLevel), su sistema realiza una llamada a la API en su lugar. Consulte Acceso a la API (la operación Crear un contacto) y Embudos. Lo único que necesita para la dirección de entrada es su clave de API, que se encuentra en su propia sección; consulte Acceso a la API. La página de Webhooks descrita aquí es exclusivamente para la dirección de salida.

Los usos comunes incluyen:

• Sincronizar nuevos contactos con su CRM.
• Activar un flujo de trabajo en Zapier, Make o Pabbly cuando se aplica una etiqueta.
• Notificar a su equipo en Slack cuando se alerta a un humano.
• Actualizar su sistema de calendario cuando se reserva una cita.
• Registrar resúmenes de conversaciones en su base de datos.

Configuración de webhooks #

1. En la barra lateral izquierda, haga clic en Configuración (icono de engranaje).
2. En la barra lateral de Configuración, bajo el grupo Integraciones, haga clic en Webhooks.

En una cuenta sin webhooks configurados todavía, la página se ve así:

3. Haz clic en New webhook, en la parte superior derecha. Se abrirá un formulario en la misma página:

4. Rellene:
   • URL del endpoint: la dirección web a la que Your AI Connector enviará las notificaciones de eventos. La obtendrá de su sistema externo (CRM, plataforma de automatización o servidor personalizado).
   • Nombre: una etiqueta que reconocerá más adelante (p. ej., “Alertas de Slack” o “Sincronización con CRM”). Solo para su referencia.

Su URL de webhook debe ser una dirección https:// alcanzable públicamente. Las direcciones http:// simples, localhost o las direcciones de red privada y las direcciones internas de la plataforma se rechazan al guardar. Para realizar pruebas desde su propia máquina, utilice un túnel público (webhook.site o ngrok) en lugar de localhost.

5. En Eventos, haga clic en los eventos que desea que reciba este webhook; los 22 se enumeran en Los 22 eventos de webhook.
6. (Opcional) Active Reintentar entregas fallidas si desea que Your AI Connector siga intentándolo ante un fallo temporal; consulte Reintento de entregas fallidas.
7. Haga clic en Crear webhook. Aparecerá en la lista debajo del formulario, y puede hacer clic en Probar en su fila en cualquier momento para enviar una carga útil de muestra a su endpoint.

Permiso necesario. Agregar, editar o probar webhooks requiere el permiso de “edición” de Integraciones (los miembros del equipo con acceso de solo lectura verán un aviso de solo lectura en lugar del formulario).

Firmar un webhook requiere que ya esté guardado primero; abra la fila de un webhook existente para editarlo y el panel Secreto de firma aparecerá en la parte inferior del formulario de edición. Un borrador nuevo y sin guardar aún no tiene opción de firma; consulte Cargas útiles firmadas a continuación.

Un webhook para todas sus cuentas de cliente (Agencias) #

Si usted dirige una agencia, no tiene que volver a crear el mismo webhook en cada cuenta de cliente. En la cuenta de agencia, el formulario de webhook tiene un interruptor adicional: Disparar también para todas las cuentas de cliente. Actívelo y este webhook también recibirá los eventos que ocurran en todas las cuentas de cliente bajo su agencia: un solo endpoint, toda la agencia.

Cómo funciona:

• El bloque user le indica a qué cliente pertenece un evento. Cada notificación ya incluye un bloque user que identifica la cuenta en la que ocurrió el evento, por lo que su automatización puede realizar el enrutamiento por cliente.
• La configuración de su webhook se aplica en todas partes. Los eventos que seleccionó, el secreto de firma y la configuración de reintento también se utilizan para las entregas de las cuentas de cliente.
• Sin entregas duplicadas. Si una cuenta de cliente tiene su propio webhook apuntando a la misma URL, ese se utilizará para los eventos de dicha cuenta en su lugar; el mismo evento nunca llega dos veces al mismo endpoint.
• Los clientes no lo ven. El webhook no aparece en la página de Webhooks de la cuenta del cliente y los clientes no pueden desactivarlo; es usted quien lo gestiona.
• La fiabilidad se rastrea por cuenta de cliente. Si su endpoint sigue fallando, se desactivará automáticamente para la cuenta cuyas entregas fallaron (consulte Fiabilidad de Webhooks), no para toda la agencia a la vez.

El interruptor solo aparece en cuentas de agencia. También se admite su configuración a través de la API; consulte el campo apply_to_sub_accounts en la API de Webhooks.

Eventos de activación disponibles #

Puede habilitar o deshabilitar cada uno de los 22 eventos de webhook de forma independiente. Cuando se activa un evento, Your AI Connector envía una notificación a su URL de webhook con los datos relevantes. Cada evento, su significado y el código event que incluye en la carga útil se enumeran juntos en Los 22 eventos de webhook más adelante en esta página.

Es bueno saberlo: Tarea creada, Tarea actualizada y Tarea completada son totalmente seleccionables y se guardan correctamente. Resumen diario creado también es una incorporación reciente. Consulta Webhook de tarea completada más abajo para ver la estructura de esa carga útil.

Activadores de webhook basados en etiquetas #

subscribed_to_tags no limita los eventos de un webhook a una etiqueta. Solo restringe qué etiquetas generan una notificación de resumen de conversación. Para recibir una solicitud cuando se aplica una etiqueta específica, configura una URL de webhook en esa etiqueta en la pestaña Etiquetas del agente (o campaña).

El formulario de webhook en sí no tiene un selector de etiquetas, ni al crear un nuevo webhook ni al editar uno, por lo que subscribed_to_tags solo se puede leer o cambiar a través de la API de Webhooks o solicitándolo al equipo de soporte.

Es bueno saberlo: editar un webhook existente que tiene una lista subscribed_to_tags (cambiarle el nombre, cambiar sus eventos, activar/desactivar reintentos) ya no borra esa lista; dado que el formulario no tiene un selector de etiquetas para enviar de vuelta, guardar desde esta página ahora deja la lista existente intacta. (Esto era un error real antes del 21 de julio de 2026: guardar desde el formulario de webhook solía borrar la lista porque siempre enviaba una lista de etiquetas vacía. Si un webhook perdió su lista subscribed_to_tags antes de esa fecha, deberá reconfigurarse a través de la API).

Generar resumen para contactos etiquetados #

Cuando un webhook tiene una lista subscribed_to_tags, puedes activar Generar resumen. Cuando está habilitado, Your AI Connector genera automáticamente un resumen de la conversación para el contacto cuando se aplica una de esas etiquetas y lo incluye en los datos del webhook: contexto completo sin necesidad de una solicitud separada.

Prueba de su webhook #

1. Abra Configuración → Integraciones → Webhooks.
2. En la fila de su webhook, haga clic en Probar.
3. Verifique su sistema externo para confirmar que recibió los datos de prueba.
4. Revise el formato de los datos para asegurarse de que su sistema pueda analizarlos correctamente.

Para una prueba completa de extremo a extremo, envíe un mensaje que active uno de sus eventos configurados (una difusión o un mensaje entrante en un canal conectado) y verifique que el webhook se active con los datos reales.

Qué se considera una entrega exitosa #

Tanto si haces clic en Test como si el evento se dispara de forma real, enviamos lo mismo:

• Una solicitud POST (nunca GET), con el cuerpo en formato JSON y Content-Type: application/json.
• Los encabezados enumerados en Cargas útiles firmadas. Los encabezados de firma solo se incluyen una vez que hayas configurado un secreto de firma.

Consideramos que la entrega es exitosa cuando:

• Tu endpoint responde con cualquier estado 2xx (200, 201, 204: todos son válidos).
• Responde en un plazo de 30 segundos.

Algunas cosas que sorprenden a los usuarios:

• El cuerpo de la respuesta se ignora. No es necesario que devuelva ningún JSON en particular. Un 200 vacío es suficiente.
• Las redirecciones cuentan como un error. No las seguimos, por lo que un 301 o 302 (incluida una redirección de barra diagonal final, o de http a https) se registra como una entrega fallida. Guarde la URL final, no una que redirija.
• Las cadenas de consulta son totalmente compatibles. https://your-app.com/hook?token=abc123 se envía exactamente como la guardó, por lo que incluir un token en la cadena de consulta funciona igual de bien que ponerlo en la ruta.
• Su URL debe ser https:// y estar disponible públicamente. Las direcciones que pertenecen a la propia infraestructura de Your AI Connector son rechazadas, pero sus propios puntos de conexión en Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting o cualquier otro lugar están bien.
• Un firewall o una capa de protección contra bots frente a su punto de conexión puede bloquearnos. El caso más común es Cloudflare: si su zona tiene activado el modo Bot Fight o un desafío gestionado, nuestra solicitud recibe una página de desafío “Just a moment…” con un 403 en lugar de llegar a su servidor; y una solicitud de servidor a servidor nunca puede superar un desafío de navegador, por lo que tanto el botón Probar como los eventos reales fallan de la misma manera. El botón Probar le indicará cuándo sucede esto (“Cloudflare está mostrando un desafío de bot a nuestra solicitud”). Soluciónelo en Cloudflare con una regla de Seguridad / WAF que omita los desafíos para su ruta de webhook (o para el agente de usuario Webhook-Delivery/1.0), luego haga clic en Probar nuevamente.
• Si su firewall necesita una lista de permitidos de IP en su lugar (por ejemplo, el plan gratuito de Cloudflare, donde el modo Bot Fight simple no se puede omitir mediante una regla WAF, pero una regla de acceso IP configurada en Permitir se ejecuta antes), podemos ayudarle: cada entrega, ya sea desde el botón Probar o un evento en vivo, se envía desde una dirección IPv4 fija (sin rangos, sin IPv6, sin rotación). Comuníquese con el soporte y le daremos la dirección para incluir en la lista de permitidos. Mantenga la verificación de firma como su comprobación de confianza real, ya que valida cada carga útil independientemente de dónde provenga.
• El resultado de la prueba le indica exactamente lo que respondió su punto de conexión. Una prueba fallida ahora muestra la razón real (el estado HTTP que devolvió su punto de conexión, un tiempo de espera o que no pudimos llegar a la dirección en absoluto) en lugar de un error genérico, y una prueba en un webhook guardado se envía firmada cuando la firma está activada, exactamente igual que un evento en vivo.

Uso de n8n, Make o Zapier (“URL de prueba” vs “URL de producción”) #

Las plataformas de automatización suelen ofrecerte dos direcciones de webhook diferentes, y esto suele confundir a los usuarios:

• Una URL de prueba (en n8n contiene /webhook-test/). Esta solo recibe datos mientras observa activamente el lienzo y acaba de hacer clic en Escuchar evento de prueba (o Probar flujo de trabajo). Captura un solo evento y luego deja de escuchar, por lo que hacer clic en Probar en Your AI Connector varias veces seguidas solo captura el primero, y solo si la ventana de escucha está activa en ese preciso momento. Para probar: primero haga clic en Escuchar evento de prueba en n8n, luego regrese a Your AI Connector y haga clic en Probar una vez.
• Una URL de producción (en n8n contiene /webhook/, sin -test). Esta es la que debe pegar en Your AI Connector para eventos en vivo. Solo funciona una vez que su flujo de trabajo se cambia a Activo. Si el flujo de trabajo no está activo, n8n rechaza la solicitud con un error “404 / webhook no registrado”, aunque Your AI Connector haya enviado los datos correctamente.

En resumen: prueba con la URL de prueba mientras escuchas, pero para que el webhook siga funcionando con contactos reales, guarda la URL de producción en Your AI Connector y asegúrate de que el flujo de trabajo esté Active.

Formato de datos del webhook #

Cuando se dispara un webhook, Your AI Connector envía datos estructurados (JSON) a su URL de webhook. Si utiliza una plataforma de automatización como Zapier o Make, esta analiza los datos automáticamente por usted. Si está creando una integración personalizada:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

campaign o agent: normalmente uno, no ambos. Si su cuenta utiliza agentes, sus contactos se asignan a un agente en lugar de a una campaña, por lo que campaign llega como null y agent le indica cuál lo gestionó. Las cuentas antiguas basadas en campañas ven lo contrario. Lea el campo que esté relleno; no asuma que campaign siempre está presente.

El bloque agent llegó el 15 de agosto de 2026. Se sitúa junto a campaign en los eventos vinculados a una conversación (un chat finalizado, no molestar, una reanudación, una desarchivación, una pausa de IA, un mensaje nuevo, un resumen de conversación y el webhook que puedes configurar en una etiqueta) y contiene el id y name del agente encargado, o null cuando no hay ningún agente involucrado. Es puramente aditivo: todos los campos que ya recibes permanecen sin cambios, por lo que cualquier receptor que hayas creado antes de esa fecha seguirá funcionando sin necesidad de actualizaciones.

Algunos eventos añaden su propio bloque adicional de nivel superior. Por ejemplo, Cita reservada (Appointment Booked) añade un bloque appointment (consulta Webhook de Cita reservada), Nuevo mensaje (New Message) añade un bloque message completo con el texto (consulta Webhook de Nuevo mensaje), y Entregas (Deliveries) y Lecturas (Reads) añaden un bloque message corto solo con el ID y el estado del mensaje (consulta Webhook de Entregas y Lecturas).

Las Entregas y Lecturas te indican qué mensaje es, pero no qué decía. Contienen un bloque message con el id y el status del mensaje — y ese id es el mismo messageId que devuelve el endpoint de envío de mensajes, por lo que puedes hacer coincidir un recibo de entrega o lectura con el mensaje exacto que enviaste —, pero no el cuerpo del mensaje. Respuestas (Replies) no contiene ningún bloque message. Si necesitas las palabras que se enviaron o recibieron, suscríbete a Nuevo mensaje junto con ellos.

Dos cosas que debe saber antes de escribir su receptor. No hay un campo timestamp ni un contenedor data. Cada bloque se encuentra en el nivel superior del objeto JSON, como se muestra arriba.

Los 22 eventos de webhook #

Los 22 eventos de webhook, con la etiqueta de visualización que marca en la aplicación y el código event enviado en la carga útil. El código event es una cadena corta que no coincide con la etiqueta de visualización, por lo que debe configurar su receptor basándose en el código, no en la etiqueta:

Nunca aparecen dos códigos más en esa lista porque no te suscribes a ellos: contact_tags_updated, enviado por una URL de webhook configurada en una etiqueta individual, y summary_generated, enviado cuando se escribe un resumen de chat para una etiqueta en la lista subscribed_to_tags de un webhook.

Canal conectado aún no se envía. Aparece en la lista de eventos, pero actualmente nada lo emite. No desarrolle basándose en él.

Las notificaciones basadas en etiquetas y tareas utilizan sus propias formas separadas. Consulte Etiquetas de contacto actualizadas y Tarea completada.

Webhook de contacto creado #

Se envía cuando se activa el evento Contacto creado (se agrega un nuevo contacto manualmente, mediante importación o mediante API).

Nombre del evento #

contactCreated

Formato de carga útil #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

La muestra de “Prueba” y un evento real se ven ligeramente diferentes. El botón de prueba envía datos de marcador de posición (John Doe, una campaña de muestra). Un evento real de Contacto creado contiene los detalles reales del contacto, y algunos campos pueden estar vacíos según el canal.

Webhook de nuevo mensaje #

Este webhook se activa cada vez que se añade un mensaje a una conversación, en cualquier canal. Cubre ambas direcciones: los mensajes que su contacto le envía a usted y los mensajes que su IA, su equipo o una campaña le envían a él. Es el único webhook que incluye el texto del mensaje, por lo que es el que debe utilizar cuando desee reflejar las conversaciones en un sistema externo.

Nombre del evento #

new_message

Formato de carga útil #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}

Todavía no hay ningún bloque campaign en esta carga útil. New Message envía contact, agent, user y message. El bloque agent se añadió el 15 de agosto de 2026 e indica qué agente gestiona la conversación; si también necesitas el contexto de la campaña, busca el contacto a través de la API utilizando contact.id.

Los registros internos de la IA no activan este webhook. Junto con los mensajes reales, la plataforma mantiene sus propias filas de contabilidad en una conversación (las llamadas a herramientas de la IA y los registros de turnos internos). Estos nunca se envían; solo recibirá los mensajes que fueron realmente enviados o recibidos.

Webhook de Entregas y Lecturas #

Estos dos eventos informan de lo que le sucedió a un mensaje después de salir de Your AI Connector: Entregas se dispara cuando un mensaje llega al contacto (o no logra hacerlo), y Lecturas se dispara cuando el contacto lo abre, en los canales que admiten recibos de lectura.

Ambos contienen un bloque message con el ID del mensaje al que se refiere el evento, para que puedas hacer coincidir la actualización con el mensaje exacto que enviaste.

Nombres de eventos #

delivered y undelivered para Entregas, read para Lecturas.

Formato de carga útil #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Cómo hacer coincidir una actualización con el mensaje que enviaste. Almacena el messageId que recibes al enviar un mensaje a través de la API. Cuando llegue una notificación de Entregas o Lecturas, busca ese ID almacenado en message.id dentro del payload; ese es tu recibo de entrega o lectura para ese mensaje exacto.

Aquí no hay texto de mensaje. El bloque message solo contiene el ID y el estado. Suscríbete a Nuevo mensaje si también necesitas el cuerpo.

El bloque message solo está presente cuando sabemos de qué mensaje se trataba. En la rara actualización que no podemos vincular a un mensaje almacenado, el bloque se omite por completo en lugar de enviarse vacío; así que verifica que message exista antes de leer message.id.

Una notificación por cambio de estado. Un solo mensaje saliente normalmente produce una notificación de delivered y luego, en canales con recibos de lectura, una de read. Un envío fallido produce undelivered en su lugar.

Webhook de cita reservada #

Se activa cuando un contacto reserva una cita. Se activa de la misma manera tanto si la IA la reservó durante una conversación, como si usted la reservó manualmente o si llegó a través de la API.

Nombre del evento #

booked

Formato de carga útil #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id suele ser null en este webhook, y eso es normal. El evento de Google Calendar se crea en el mismo momento en que sale esta notificación, por lo que el ID generalmente aún no está listo. Vuelva a obtener la cita por su appointment_id un momento después si lo necesita. Permanece como null permanentemente si la cuenta no tiene Google Calendar conectado, así que no espere por él indefinidamente.

El botón “Probar” no incluye el bloque appointment. Úselo para confirmar que su punto final responde, luego realice una reserva real para ver la carga útil completa.

Dos casos en los que este webhook no se activa: citas importadas desde un calendario externo y reservas que provienen de la integración con Formitable.

Webhook de actualización de etiquetas de contacto #

Se activa cuando se aplica una etiqueta a un contacto y dicha etiqueta tiene una URL de webhook configurada en el agente o la campaña a la que pertenece el contacto.

Nombre del evento #

contact_tags_updated

Cuándo se activa #

• Se aplica una etiqueta a un contacto que tiene un agente asignado, una campaña asignada o ambos.
• Al menos una de las etiquetas aplicadas tiene una URL de webhook configurada en la pestaña Etiquetas de ese agente o campaña.

Si el contacto tiene ambos y las etiquetas de la campaña llevan URLs de webhook, estas prevalecen; de lo contrario, se utilizan las del agente.

Si se aplican varias etiquetas con diferentes URL de webhook en la misma actualización, se envía una solicitud por cada URL, conteniendo cada una solo las etiquetas que corresponden a esa URL.

Eliminar una etiqueta nunca envía una solicitud. La mayoría de las personas dirigen estas URL a una acción (cobrar un depósito, reservar un espacio, alertar a un representante), por lo que una etiqueta que se elimina de un contacto solía volver a ejecutar esa acción. Ya no puede hacerlo. Una eliminación sigue apareciendo en removed_tags cuando ocurre en la misma actualización que una aplicación que va a la misma URL, por lo que una automatización que lee ambas matrices mantiene la imagen completa; lo que nunca verá es una solicitud causada únicamente por una eliminación. (Cambiado el 12 de agosto de 2026. Antes de esa fecha, las eliminaciones también enviaban una solicitud).

Formato de carga útil #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Probar un webhook de etiqueta #

Junto al campo de URL del webhook en la pestaña Etiquetas, hay un botón Probar. Envía una carga útil de muestra a esa URL inmediatamente, para que pueda confirmar que su automatización la recibe antes de esperar a una conversación real.

La prueba envía la misma forma de contact_tags_updated que se muestra arriba, utilizando un contacto de marcador de posición, con la etiqueta que está probando en added_tags y un removed_tags vacío. Lo que su automatización ve en la prueba es lo que verá en producción.

Dos cosas que debe saber:

• Guarda la etiqueta primero. La prueba busca la etiqueta por su nombre guardado, por lo que una etiqueta nueva o un cambio de nombre no guardado aún no se pueden probar. El botón permanece desactivado hasta que el nombre en pantalla coincida con el guardado.
• Una prueba fallida no cuenta en contra de tu webhook. Las pruebas nunca contribuyen al apagado automático tras fallos repetidos descrito en Fiabilidad del webhook.

Si la prueba falla, el mensaje le indica lo que respondió su punto final (por ejemplo, un 404 o un 500), lo cual suele ser suficiente para detectar una URL incorrecta o un flujo de trabajo que no está activado.

Webhook de tarea completada #

Solo como referencia. Los webhooks de tareas (como datos) están documentados aquí para desarrolladores; los eventos Tarea creada, Tarea actualizada y Tarea completada se pueden seleccionar en la lista de eventos estándar en el formulario de webhook como cualquier otro evento; consulte Eventos de activación disponibles y Los 22 eventos de webhook.

Esta carga útil se envía cuando una tarea pasa a una etapa marcada como etapa de finalización. Una tarea que se mueve entre etapas que no son de finalización envía el formato taskUpdated en su lugar.

Nombre del evento #

taskCompleted

Cuándo se activa #

• Se actualiza una tarea.
• Su valor stage cambió en comparación con su valor anterior.
• La nueva etapa está configurada como una etapa de finalización en la configuración de etapas de tareas de la cuenta.

Formato de carga útil #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Desactivar un webhook (o eliminarlo) #

Cada webhook tiene un interruptor de encendido/apagado, justo en su fila. Desactivarlo (off) detiene la recepción de eventos, pero mantiene todo lo que configuró: la URL, los eventos y cualquier secreto de firma. Vuelva a activarlo y continuará desde donde lo dejó; nada de lo que haya ocurrido mientras estaba desactivado se entregará posteriormente.

Úselo cuando desee que las entregas se detengan por un tiempo: su endpoint se está reconstruyendo, está depurando una integración ruidosa o está pausando una automatización.

Eliminar un webhook (el icono de la papelera en su fila) lo elimina definitivamente, incluido su secreto de firma. Si solo desea que las entregas se detengan, desactívelo en su lugar; la eliminación es para cuando haya terminado por completo con el endpoint.

Esto no es lo mismo que desactivar un webhook automáticamente. Si desactivamos su webhook tras fallos repetidos (consulte Fiabilidad de los Webhooks), el interruptor de arriba no lo volverá a activar. Una vez que su endpoint esté corregido, edite el webhook y guárdelo con una URL distinta (cualquier cambio de URL lo reactiva), o llame al endpoint de reactivación a través de la API, o póngase en contacto con el soporte técnico y lo reactivaremos por usted.

Cargas útiles firmadas (verificar que un webhook realmente provino de nosotros) #

Cualquiera que conozca la URL de su webhook podría enviarle una solicitud falsa. Si actúa sobre los webhooks automáticamente (actualizando la facturación, creando registros en el CRM), activar la firma le permite verificar que cada solicitud provino realmente de nosotros.

La firma es opcional y está desactivada de forma predeterminada, y se activa por cada webhook desde la vista de edición de dicho webhook (abra la fila de un webhook guardado).

Activación de la firma #

1. Abra el webhook (Configuración → Integraciones → Webhooks → haga clic en la fila de su webhook).
2. En la sección Secreto de firma, haga clic en Generar.
3. Copie el secreto (comienza con whsec_) y guárdelo en su sistema receptor. Trátelo como una contraseña.

Puede volver y revelar, copiar, rotar o desactivar el secreto en cualquier momento desde este mismo panel.

Lo que enviamos #

Una vez activada la firma, cada entrega para ese webhook lleva estos dos encabezados HTTP adicionales:

Estos tres están en cada entrega, firmada o no:

Cómo verificar #

La firma es un HMAC-SHA256 de la cadena <timestamp>.<raw request body>, utilizando su secreto de firma como clave.

Verifique contra el cuerpo de la solicitud sin procesar: los bytes exactos que recibió. Si su framework analiza el JSON y lo vuelve a serializar antes de comprobarlo, los bytes pueden cambiar y la firma no coincidirá.

Ejemplo en Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Ejemplo en Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Compare las firmas con una función de tiempo constante (timingSafeEqual / compare_digest), no con ==. No cuesta nada y evita una clase sutil de ataque.

Rotación del secreto #

Haga clic en Rotar para reemplazar el secreto. El cambio es inmediato: la siguiente entrega se firma únicamente con el nuevo secreto. Si su endpoint está activo, acepte tanto el secreto antiguo como el nuevo durante unos minutos mientras implementa el nuevo.

Desactivar la firma simplemente evita que se envíen los encabezados de firma.

Reintento de entregas fallidas #

De forma predeterminada, una entrega que falla no se vuelve a intentar; si su sistema no está disponible en ese momento, se pierde el evento.

Active Reintentar entregas fallidas en un webhook (en el formulario de creación/edición) y seguiremos intentándolo:

Eso abarca aproximadamente 2 horas y 40 minutos, por lo que un webhook puede sobrevivir a una ventana de mantenimiento o a una breve interrupción de su parte.

Qué se reintenta: problemas temporales: su servidor devuelve un error 5xx, un tiempo de espera agotado o un error de conexión.

Qué no se reintenta: si su endpoint rechaza la solicitud en sí (cualquier 4xx), no reintentamos; enviar la misma solicitud de nuevo solo produciría el mismo rechazo.

Qué eventos se reintentan: webhooks de etiquetas (contact_tags_updated), los tres eventos de tareas y el resumen diario. El resto se envían una vez, por lo que para ellos el interruptor no tiene nada sobre lo que actuar. Cada evento sigue llevando X-Webhook-Delivery, por lo que una regla de deduplicación los cubre todos.

Active los reintentos solo si su endpoint es idempotente. Los reintentos significan que el mismo evento puede llegar más de una vez. Utilice el encabezado X-Webhook-Delivery para reconocer una repetición: permanece igual en cada intento para un mismo evento, por lo que puede ignorar de forma segura un ID que ya haya procesado.

Los reintentos interactúan con la desactivación automática tras fallos repetidos (consulte Fiabilidad de los webhooks) de la forma que usted desea: el contador de fallos cuenta una entrega completa, solo después de que se hayan agotado todos los reintentos, no cada intento individual.

Fiabilidad del Webhook #

• Your AI Connector envía webhooks a través de una conexión segura (HTTPS). Asegúrese de que la dirección web que proporcione utilice HTTPS.
• Si su sistema devuelve un error, la entrega se considera fallida.
• Supervise el tiempo de actividad de su sistema receptor para evitar perder eventos.
• Para flujos de trabajo críticos, active Reintento de entregas fallidas y considere también un mecanismo de respaldo.

Los webhooks se desactivan automáticamente tras fallos repetidos. Si la URL de su webhook falla repetidamente (aproximadamente 5 errores seguidos, o 3 seguidos en caso de errores de configuración), Your AI Connector dejará de enviar eventos a esa URL automáticamente. Para reactivarlo una vez que su endpoint funcione correctamente: edite el webhook y guárdelo con una URL distinta (cualquier cambio de URL lo reactiva), o utilice el endpoint de reactivación a través de la API; guardar de nuevo con la misma URL no es suficiente. El equipo de soporte también puede reactivarlo por usted.

Solución de problemas #

Próximos pasos #

• Integración con GoHighLevel: utilice webhooks para integrar Your AI Connector con GHL.
• Acceso a la API: combine webhooks con la API para obtener automatizaciones potentes.
• Uso de etiquetas para clasificar contactos: configure etiquetas que activen sus webhooks.