Bloque de respuesta de webhook, envía respuestas HTTP personalizadas

Envía respuestas personalizadas en JSON, XML o texto plano al sistema que activó tu webhook de ChatMaxima. Configura el código de estado, el tipo de contenido y el cuerpo.

Visión general

El bloque de respuesta de webhook te permite enviar una respuesta HTTP personalizada al sistema que llamó a tu bloque de webhook. Sin este bloque, ChatMaxima responde con un 200 OK genérico y un cuerpo de {"status":"success"}. Eso está bien para la mayoría de las devoluciones de llamada, pero algunas integraciones esperan una forma, un código de estado o un tipo de contenido específicos antes de considerar exitosa la entrega.

Usa el bloque de respuesta de webhook cuando el emisor sea estricto con la respuesta: pasarelas de pago que reintentan a menos que vean un campo JSON concreto, sistemas SOAP heredados que esperan XML, herramientas iPaaS que analizan la respuesta en pasos posteriores o constructores de formularios que muestran la respuesta al usuario.

Bloque de webhook frente a bloque de respuesta de webhook

Aspecto	Bloque de webhook	Bloque de respuesta de webhook
Dirección	Recibe una llamada HTTP entrante	Envía una respuesta HTTP al emisor
Ubicación	Primer bloque o intermedio	En cualquier lugar posterior a un bloque de webhook
Obligatorio	Sí (para aceptar llamadas externas)	Opcional (se envía un `200 OK` predeterminado si se omite)
Propósito	Activar o reanudar el flujo	Dar forma a la respuesta HTTP al emisor

Dónde encontrarlo

Abre tu chatbot en Studio
Arrastra el bloque de respuesta de webhook desde la barra lateral izquierda al lienzo
Conéctalo después del bloque de webhook que recibió la solicitud
Haz doble clic en el bloque para configurarlo

El bloque de respuesta de webhook no necesita ser el bloque inmediatamente siguiente. Puedes colocar bloques de condición, de API, de establecer variable y de mensaje entre el bloque de webhook y el bloque de respuesta de webhook. Cuando se alcanza el bloque de respuesta durante la ejecución del flujo, su configuración se convierte en la respuesta HTTP al emisor original.

Configuración

Paso 1: Establece el código de estado HTTP

Código de estado	Úsalo cuando
`200`	Predeterminado. Indica éxito a la mayoría de los emisores
`201`	Útil cuando el webhook creó un recurso (p. ej., una nueva conversación)
`202`	Aceptado para procesamiento asíncrono (el bot actuará sobre ello más tarde)
`400`	Rechaza cargas mal formadas
`401`	Rechaza emisores no autorizados
`500`	Indica un fallo del lado del bot para la lógica de reintentos

Paso 2: Establece el Content-Type

Content-Type	Úsalo cuando
`application/json`	La mayoría de las integraciones modernas (predeterminado)
`application/xml`	Emisores de estilo SOAP heredados
`text/plain`	Devoluciones de llamada tipo comprobación de estado
`text/html`	Confirmaciones de envío de formularios mostradas a un usuario

Paso 3: Escribe el cuerpo de la respuesta

El cuerpo es un campo de texto libre. Escribe la carga exacta que quieres devolver al emisor. Las variables capturadas antes en el flujo se pueden insertar con la sintaxis {variable_name} (llaves simples).

Para JSON:

{
  "received": true,
  "conversation_id": "{conversation_id}",
  "lead_id": "{reference_id}",
  "acknowledged_at": "{current_time}"
}

Para XML:

<response>
  <status>success</status>
  <conversation_id>{conversation_id}</conversation_id>
</response>

Para texto plano:

OK

Paso 4: 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.

Cómo funciona

External system POSTs to webhook URL
                 │
                 ▼
       Webhook Block fires
                 │
                 ▼
   (Optional) intermediate blocks:
   - Condition to validate payload
   - API Block to enrich data
   - Set Variable to compute fields
                 │
                 ▼
    Webhook Response Block reached
                 │
                 ▼
    Custom HTTP response returned
    to the original caller
                 │
                 ▼
    Flow continues to downstream blocks
    (messages, further logic, etc.)

La respuesta HTTP se envía de forma síncrona: el emisor externo permanece conectado hasta que se alcanza el bloque de respuesta. Por ello, mantén rápida la ruta entre el bloque de webhook y el bloque de respuesta de webhook. Evita las llamadas a la API de larga duración o la lógica que consuma tiempo antes del bloque de respuesta, de lo contrario el emisor podría agotar su tiempo de espera.

Casos de uso comunes

Confirmar con el ID de conversación

Una herramienta iPaaS (n8n, Zapier, Make) quiere registrar el ID de la conversación en su propio sistema tras activar el webhook.

Código de estado: 201
Content-Type: application/json
Cuerpo:

{
  "created": true,
  "conversation_id": "{conversation_id}",
  "reference_id": "{reference_id}"
}

Devolver el resultado de la validación

Un constructor de formularios envía la entrada del usuario. El bot la valida y devuelve un resultado de éxito o fallo para que el formulario muestre el mensaje correcto.

Código de estado: 200
Content-Type: application/json
Cuerpo:

{
  "valid": true,
  "message": "Your request has been received"
}

Rechazar cargas no válidas

Combina un bloque de condición (que comprueba los campos obligatorios) con un bloque de respuesta de webhook en la rama de fallo que devuelve 400.

Código de estado: 400
Content-Type: application/json
Cuerpo:

{
  "error": "missing_required_field",
  "field": "{missing_field}"
}

Confirmación de una pasarela de pago

Una pasarela de pago envía un webhook settle. El bot tiene que devolver una forma JSON específica o la pasarela seguirá reintentando.

Código de estado: 200
Content-Type: application/json
Cuerpo:

{
  "status": "acknowledged",
  "transaction_id": "{transaction_id}"
}

Acuse de entrega de SMS

Un proveedor de SMS heredado espera una respuesta de texto plano OK.

Código de estado: 200
Content-Type: text/plain
Cuerpo: OK

Buenas prácticas

Mantén la ruta corta. Coloca bloques entre el webhook y la respuesta de webhook solo si se ejecutan rápido. Las llamadas a la API largas deben ir después del bloque de respuesta para que el emisor no agote su tiempo de espera
Responde siempre rápido a los emisores que reintentan. Las pasarelas de pago y los proveedores de SMS suelen reintentar en segundos. Alcanzar el bloque de respuesta en uno o dos segundos evita notificaciones duplicadas
Coincide exactamente con la forma que espera el emisor. Los emisores estrictos rechazan las respuestas incluso cuando el código de estado es correcto. Lee la documentación de la integración y prueba con sus solicitudes de ejemplo
Usa bloques de condición para ramificar la respuesta. Ten un bloque de respuesta de webhook en la rama de éxito y otro distinto (con 400 o 401) en la rama de fallo
Incluye el ID de conversación o de referencia. Esto facilita correlacionar los registros del emisor con la conversación en ChatMaxima
No incluyas datos sensibles en la respuesta. La respuesta es visible para el emisor. Devuelve solo lo que necesita para confirmar la recepción

Solución de problemas

El emisor recibe el `200 OK` predeterminado en lugar de mi respuesta personalizada

Confirma que hay un bloque de respuesta de webhook presente y alcanzable desde el bloque de webhook
Comprueba el grafo del flujo: si una condición rodea el bloque de respuesta, se usa el predeterminado
Asegúrate de que el bloque se guardó. Haz clic en Enviar en el modal y luego en Guardar cambios en la barra superior

El emisor reintenta de forma repetida

Asegúrate de que el código de estado coincide con lo que el emisor considera éxito. Algunos proveedores solo aceptan 200, no 201 ni 202
Verifica que el cuerpo de la respuesta coincide con la forma esperada por el emisor. Revisa su documentación o sus registros
Comprueba si hay bloques previos lentos entre el webhook y la respuesta de webhook. El emisor podría estar agotando su tiempo de espera antes de que se envíe la respuesta

Las variables aparecen como `{variable_name}` sin procesar en el cuerpo de la respuesta

Confirma que la variable fue establecida por un bloque anterior en el mismo flujo
Los nombres de variable son sensibles a mayúsculas. Revisa la ortografía
Para campos anidados, usa notación de puntos: {customer.email}, no {customer_email}
Si la variable proviene de la carga del webhook entrante, asegúrate de que la carga realmente contenía el campo

Los emisores estrictos rechazan el JSON mal formado

Valida la plantilla del cuerpo como JSON antes de guardar. Una variable sin comillas en un campo de cadena producirá un JSON no válido si el valor contiene comillas o saltos de línea
Para campos numéricos como {amount}, no los envuelvas en comillas. Para campos de cadena, envuélvelos siempre: "name": "{name}"
Prueba con una llamada de ejemplo (con curl o Postman) para ver los bytes reales devueltos

Desajuste de Content-Type

Algunos emisores requieren application/json; charset=utf-8 de forma explícita. El predeterminado envía application/json sin el charset
Los clientes SOAP pueden requerir text/xml en lugar de application/xml. Revisa la documentación de la integración

Próximos pasos

Bloque de webhook: recibe llamadas HTTP entrantes para activar o reanudar un flujo
Bloque de API: llama a APIs externas desde el flujo
Visión general de Studio: explora todos los tipos de bloque y las funciones del constructor de flujos