Bloque de webhook, recibe llamadas HTTP entrantes en tu chatbot

Pausa el flujo de tu chatbot de ChatMaxima y espera una llamada HTTP externa. Recibe cargas, reanuda el flujo y envía respuestas HTTP personalizadas al emisor.

Visión general

El bloque de webhook permite que un sistema externo llame a tu chatbot por HTTP. Se puede usar de dos formas: como primer bloque de un flujo (el propio webhook inicia la conversación) o como bloque intermedio que pausa la conversación y espera una devolución de llamada externa para reanudarla. En ambos casos, la carga entrante se analiza y se pone a disposición de los bloques posteriores como variables. Opcionalmente puedes enviar una respuesta HTTP personalizada al emisor usando el bloque de respuesta de webhook.

Este es el inverso del bloque de API. El bloque de API envía solicitudes salientes. El bloque de webhook escucha solicitudes entrantes. Los casos de uso habituales incluyen iniciar una nueva conversación a partir de un evento externo (el envío de un formulario, la creación de un registro en el CRM, un activador de un iPaaS como n8n o Zapier), esperar la devolución de llamada de una pasarela de pago, recibir la confirmación de entrega de un OTP de un proveedor de SMS de terceros, recibir aviso cuando se completa una tarea de backend de larga duración o aceptar actualizaciones asíncronas de una app externa.

Bloque de webhook frente a bloque de API

Aspecto	Bloque de API	Bloque de webhook
Dirección	Saliente (el bot llama a la API)	Entrante (un sistema externo llama al bot)
Activador	Automático cuando el flujo llega al bloque	Un POST HTTP externo inicia o reanuda el flujo
Ubicación	Solo intermedio	Primer bloque o intermedio
Comportamiento de espera	Síncrono, tiempo de espera de 30 segundos	Inicia el flujo al llegar, o pausa el flujo hasta que llega la llamada
Uso típico	Buscar datos, enviar actualizaciones	Iniciar conversaciones desde eventos externos, esperar devoluciones de llamada asíncronas
Manejo de la respuesta	Analiza el cuerpo de la respuesta en variables	La carga entrante se convierte en variables

Dónde encontrarlo

Abre tu chatbot en Studio
Arrastra el bloque webhook desde la barra lateral izquierda al lienzo
Colócalo como primer bloque de tu flujo (para iniciar una conversación desde un evento externo) o conéctalo después de cualquier bloque anterior (para pausar y esperar una devolución de llamada a mitad del flujo)
Haz doble clic en el bloque para configurarlo

Para enviar una respuesta HTTP personalizada al emisor, añade un bloque de respuesta de webhook inmediatamente después del bloque de webhook.

Webhook como primer bloque

Cuando el bloque de webhook es el primer bloque del flujo, todavía no hay una conversación activa. El POST externo crea la conversación, analiza la carga en variables e inicia el flujo desde el principio. Este es el patrón a usar cuando:

Se crea un nuevo lead en tu CRM y quieres que el bot lo contacte
Se envía un formulario en tu sitio web y quieres que el bot haga el seguimiento
Un flujo de trabajo de n8n, Zapier o Make activa una nueva sesión de chat
Un evento de backend (pedido realizado, ticket de soporte abierto) debería iniciar una conversación del bot

Webhook intermedio

Cuando el bloque de webhook se coloca después de otro bloque, el flujo se pausa en ese punto hasta que llega el POST externo. Este es el patrón a usar cuando necesitas delegar en un sistema externo, esperar su respuesta asíncrona y luego continuar el flujo según lo que devolvió.

Cómo funciona

Modo de primer bloque

External system POSTs to webhook URL
                 │
                 ▼
   New conversation is created
                 │
                 ▼
   Payload parsed into variables
                 │
                 ▼
   Flow starts from the next block
                 │
                 ▼
   Webhook Response sent (optional)

Modo intermedio

Bot flow runs ──▶ Reaches Webhook Block ──▶ Flow pauses
                                                  │
                             External system POSTs to webhook URL
                                                  │
                                                  ▼
                            Payload parsed into variables
                                                  │
                                                  ▼
                     Webhook Response sent (optional)
                                                  │
                                                  ▼
                     Flow continues to next block

En el modo intermedio, el bot almacena la posición del bloque actual cuando se pausa. Cuando el POST externo llega a la URL del webhook, el sistema lo asocia a la conversación pausada, la reanuda desde ese bloque y continúa hacia adelante.

Configuración

Paso 1: Coloca el bloque de webhook en el flujo

Arrastra el bloque al lienzo en el punto donde el flujo deba iniciarse o esperar un evento externo. Por ejemplo:

Como primer bloque, para permitir que un CRM, un formulario o una herramienta iPaaS inicie una nueva conversación de chat
Después de capturar los datos de pago, para esperar la confirmación de la pasarela de pago
Después de activar una tarea de backend mediante un bloque de API, para esperar la notificación de tarea completada

Paso 2: Copia la URL del webhook

Cada bloque de webhook expone una URL única que se muestra en la configuración del bloque. El formato es:

https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/

Pasa esta URL al sistema externo como destino de su solicitud POST. Para herramientas iPaaS (n8n, Zapier, Make) la pegas en el paso HTTP. Para CRM y constructores de formularios, configúrala como un webhook saliente en su panel. Para pasarelas de pago y backends asíncronos, establécela como URL de devolución de llamada cuando inicias el trabajo.

Paso 3: Autentica al emisor

La URL del webhook acepta un token Bearer en el encabezado Authorization. Usa el token que se muestra en la configuración del bloque para que el webhook solo acepte llamadas de sistemas en los que confíes.

curl -X POST https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_token>' \
  --data '{
    "type": "Conversation",
    "channel": "",
    "account_alias": "",
    "reference_id": "",
    "data": {
      "name": ""
    }
  }'

Forma de la carga

Campo	Propósito
`type`	Tipo de evento, normalmente `Conversation` para iniciar o reanudar un chat
`channel`	Canal que debe usar la conversación (p. ej., `whatsapp`, `website`). Déjalo vacío para usar el predeterminado
`account_alias`	Alias del equipo cuando el bot se comparte entre varias cuentas
`reference_id`	Identificador externo que puedes usar para vincular la conversación con un registro en tu sistema
`data`	Objeto que contiene los campos que quieres pasar como variables (p. ej., `name`, `email`, `phone`, campos personalizados)

Paso 4: Referencia los campos de la carga entrante

Cuando llega el POST, el objeto data se analiza y cada campo se convierte en una variable disponible para todos los bloques posteriores.

Para una carga como:

{
  "type": "Conversation",
  "channel": "whatsapp",
  "reference_id": "ORDER-9981",
  "data": {
    "name": "Priya",
    "phone": "+919000000000",
    "order_id": "ORDER-9981",
    "customer": {
      "email": "priya@example.com"
    }
  }
}

Puedes referenciar:

{name} para Priya
{phone} para +919000000000
{order_id} para ORDER-9981
{customer.email} para campos anidados
{reference_id} para metadatos de nivel superior

Paso 5: Envía y guarda

Haz clic en Enviar en el modal del bloque y luego guarda el flujo con Guardar cambios en la barra superior.

Bloque de respuesta de webhook

Empareja el bloque de webhook con un bloque de respuesta de webhook cuando el emisor espere una respuesta HTTP específica. Sin el bloque de respuesta, el bot devuelve un 200 OK predeterminado con {"status":"success"}.

El bloque de respuesta de webhook te permite personalizar el código de estado (p. ej., 201, 400, 500), el tipo de contenido (application/json, application/xml, text/plain, text/html) y el cuerpo de la respuesta que se envía al emisor. Puedes insertar variables del flujo con la sintaxis {variable_name}.

Patrones habituales:

Devolver 201 Created con el nuevo {conversation_id} para herramientas iPaaS
Devolver 400 con un campo de error cuando la carga no es válida
Devolver text/plain OK para devoluciones de llamada de entrega de SMS
Devolver XML para integraciones SOAP heredadas

Consulta la documentación completa del bloque de respuesta de webhook para ver las opciones de configuración, ejemplos y solución de problemas.

Buenas prácticas

Valida siempre las cargas entrantes. Usa un bloque de condición después del bloque de webhook para verificar campos como status == "success" antes de continuar
Usa el bloque de respuesta de webhook cuando el emisor (pasarela de pago, proveedor de SMS, etc.) espere un formato de confirmación específico. Sin él, el emisor recibe un 200 OK genérico
Establece un tiempo de espera significativo en otro lugar. El bloque de webhook en sí no expira, así que combínalo con el tiempo de espera por inactividad para evitar flujos que queden pausados indefinidamente
Protege la URL del webhook. El token de la URL es único por conversación. No expongas la URL públicamente ni la registres en sistemas que el usuario pueda leer
Gestiona el caso de fallo. Ramifica el flujo según la carga entrante. Si el evento externo indica un fallo, envía un mensaje de recuperación o enruta a un agente

Casos de uso comunes

Un lead del CRM crea una conversación (primer bloque)

Se añade un nuevo lead en tu CRM y el bot abre una conversación de WhatsApp para calificarlo.

Bloque de webhook (primer bloque): el CRM envía por POST la carga del lead con phone, name, source
Bloque de mensaje: Hi {name}, thanks for your interest!
Bloque de pregunta: hace preguntas de calificación
Bloque de API: envía los datos calificados de vuelta al CRM

Activador de n8n o Zapier (primer bloque)

Una herramienta de automatización dispara un webhook cuando ocurre un evento específico (nuevo pedido de Shopify, envío de Typeform, etc.) y el bot hace el seguimiento con el cliente.

Bloque de webhook (primer bloque): n8n envía por POST {"phone":"...", "order_id":"..."}
Bloque de mensaje: Your order {order_id} has shipped!

Devolución de llamada de una pasarela de pago

El usuario inicia un pago, el bot lo envía a una página de pago y luego espera a que la pasarela envíe el resultado por POST.

Bloque de API: crea la sesión de pago, almacena payment_url
Bloque de mensaje: envía payment_url al usuario
Bloque de webhook: pausa el flujo, pasa la URL del webhook a la pasarela como devolución de llamada
Bloque de condición: ramifica según {status} == "success"
Bloque de respuesta de webhook: devuelve {"received":true} a la pasarela

Notificación de tarea asíncrona

El bot activa una tarea de generación de informes de larga duración, espera a que se complete y luego envía el enlace del informe al usuario.

Bloque de API: envía la tarea, almacena job_id, incluye la URL del webhook como devolución de llamada
Bloque de mensaje: "Generando tu informe, esto puede tardar un momento..."
Bloque de webhook: espera la devolución de llamada de tarea completada
Bloque de mensaje: Your report is ready: {report_url}

Estado de entrega de OTP de un tercero

El bot envía un OTP a través de un proveedor de SMS externo que usa webhooks para confirmar la entrega.

Bloque de API: activa el envío del OTP, pasa la URL del webhook
Bloque de webhook: espera el estado de entrega
Bloque de condición: ramifica según {delivery_status}
Bloque de mensaje: pide el código OTP o se disculpa por el fallo de entrega

Envío de un formulario externo

Una app web independiente recopila información adicional y la envía por POST al bot cuando el usuario termina.

Bloque de mensaje: envía la URL del formulario al usuario
Bloque de webhook: espera el envío del formulario
Bloque de mensaje: Thanks, we received your {form_field}

Solución de problemas

El flujo se queda atascado en el bloque de webhook (intermedio)

Confirma que el sistema externo realmente envió un POST a la URL del webhook. Revisa sus registros de entrega
Verifica que la URL es accesible desde el sistema externo (no está bloqueada por un firewall ni por una lista de IP permitidas)
Asegúrate de que la URL incluye la ruta completa y el token final
Combínalo con el tiempo de espera por inactividad para cerrar automáticamente las conversaciones que nunca reciben la devolución de llamada

El webhook de primer bloque no inicia una conversación

Confirma que el bloque de webhook es el primerísimo bloque del flujo (ningún otro bloque se conecta a él)
Verifica que la carga incluye un identificador de destinatario (teléfono, correo o ID de visitante) que el bot pueda usar para crear la conversación
Comprueba que el bot está publicado y que el canal (WhatsApp, widget del sitio web, etc.) está conectado
Inspecciona el estado de la respuesta devuelta al emisor. Un 4xx indica que la carga fue rechazada

Los campos de la carga entrante están vacíos en los bloques posteriores

Confirma que el Content-Type del POST entrante es application/json o un tipo de formulario admitido
Comprueba los nombres exactos de los campos en la carga. Los nombres de variable son sensibles a mayúsculas
Para campos anidados, usa notación de puntos: {customer.email}, no {customer_email}
Inspecciona la carga entrante sin procesar en el registro de la conversación para ver qué se recibió realmente

El emisor recibe un `200 OK` genérico en lugar de mi respuesta personalizada

Asegúrate de haber añadido un bloque de respuesta de webhook después del bloque de webhook
Verifica que el bloque de respuesta es alcanzable en el grafo del flujo. Un bloque de condición podría estar rodeándolo
Vuelve a comprobar que hiciste clic en el botón Enviar y que el flujo se guardó

El sistema externo rechaza la respuesta del webhook

Confirma que el Content-Type coincide con lo que espera el emisor (por ejemplo, application/json frente a text/plain)
Valida que el cuerpo de la respuesta está bien formado. Un objeto JSON sin cerrar hará que los emisores estrictos reintenten
Comprueba el código de estado HTTP. Algunos emisores solo aceptan 200, no 201 ni 202

Llegan varios POST para la misma conversación

Algunos sistemas externos reintentan los webhooks si creen que la primera entrega falló. La URL del webhook es idempotente por conversación, así que solo el primer POST válido reanuda el flujo. Los POST posteriores reciben la respuesta configurada sin hacer avanzar el flujo de nuevo.

Próximos pasos

Bloque de respuesta de webhook: envía respuestas HTTP personalizadas al emisor
Bloque de API: llama a APIs externas desde el flujo
Tiempo de espera por inactividad: cierra automáticamente las conversaciones que quedan pausadas demasiado tiempo
Bloque de fin de conversación: finaliza conversaciones manualmente con un botón de reinicio
Visión general de Studio: explora todos los tipos de bloque y las funciones del constructor de flujos