Webhook

El nodo Webhook convierte tu workflow en un endpoint HTTP accesible desde cualquier sistema externo. Permite dos flujos principales: iniciar nuevas ejecuciones y reanudar ejecuciones existentes — todo mediante una simple llamada HTTP. Piensa en este nodo como la puerta de entrada de tu workflow: sistemas externos tocan la puerta (envían un request HTTP), y tu flujo decide qué hacer con lo que traen.

El nodo Webhook está disponible tanto en Tools como en Workflows. Solo puede existir un nodo Webhook por canvas.

Modos de operación

El nodo Webhook opera en dos modos, determinados automáticamente por la presencia del executionId:

Iniciar nueva ejecución

Cuando el request no incluye un executionId, el webhook crea una nueva ejecución del workflow desde cero. Caso de uso: Un sistema externo (CRM, ERP, pasarela de pagos) necesita disparar un proceso automatizado en Jelou.

curl -X POST https://brain.jelou.ai/v1/webhook/{webhookId} \
  -H "Content-Type: application/json" \
  -d '{"evento": "nuevo_pedido", "cliente": "12345"}'

Reanudar ejecución existente

Cuando el request incluye un executionId, el webhook reanuda una ejecución que estaba pausada esperando una respuesta externa. Caso de uso: Una pasarela de pagos notifica que el pago fue procesado, y el flujo debe continuar desde donde se detuvo.

curl -X POST https://brain.jelou.ai/v1/webhook/{webhookId} \
  -H "Content-Type: application/json" \
  -d '{"executionId": "abc-123", "status": "paid"}'

El executionId puede enviarse en el body (usando el path configurado en dot notation) o como query param executionId. Esto permite usar métodos HTTP como GET que no tienen body.

Configuración

Nombre de la variable

Define el nombre bajo el cual se almacenarán los datos del webhook dentro de la variable $webhook. Los datos recibidos por el request quedarán disponibles en $webhook.<nombreVariable>. Por ejemplo, si defines miWebhook, podrás acceder al body via {{$webhook.miWebhook.body}}, a los headers via {{$webhook.miWebhook.headers}}, etc.

Método HTTP

Selecciona los métodos HTTP que acepta el webhook. Soporta GET, POST, PUT, PATCH y DELETE.

Para métodos sin body (como GET), el executionId para reanudar debe enviarse como query param: ?executionId=abc-123.

Reanudar múltiples veces (oneTimeOnly)

Por defecto, una ejecución puede ser reanudada más de una vez por el webhook. Si necesitas restringir esto — por ejemplo, en integraciones de pagos donde una confirmación solo debe procesarse una vez — puedes activar la opción “Solo reanudar una vez” en la configuración avanzada.

Configuración	Comportamiento
oneTimeOnly desactivado (por defecto)	El webhook puede reanudar la misma ejecución múltiples veces
oneTimeOnly activado	El webhook solo reanuda la ejecución una vez; intentos posteriores son ignorados

Variable `$webhook`

Cuando un request llega al nodo Webhook, toda la información del request queda disponible a través de la variable $webhook. Funciona de manera similar a $memory y $context.

Propiedad	Descripción	Ejemplo
`$webhook.<nombreVariable>.body`	Cuerpo del request HTTP	`{"evento": "pago_exitoso", "monto": 50}`
`$webhook.<nombreVariable>.headers`	Headers enviados en el request	`{"content-type": "application/json"}`
`$webhook.<nombreVariable>.query`	Query params de la URL	`{"ref": "campaign-123"}`
`$webhook.<nombreVariable>.method`	Método HTTP utilizado	`POST`
`$webhook.<nombreVariable>.mode`	Modo de la ejecución	`new` o `resume`
`$webhook.<nombreVariable>.executionId`	ID de la ejecución actual	`exec-abc-123`
`$webhook.<nombreVariable>.isNewExecution`	Indica si es una ejecución nueva	`true` o `false`

Ejemplo de uso en el flujo

Suponiendo que definiste miWebhook como nombre de la variable, puedes usar las propiedades en cualquier nodo posterior:

# En un nodo Condicional
{{$webhook.miWebhook.body.evento}} == "pago_exitoso"

# En un nodo Texto
El pago de {{$webhook.miWebhook.body.monto}} fue procesado correctamente.

# En un nodo API
Authorization: {{$webhook.miWebhook.headers.authorization}}

Webhook en Workflows

El nodo Webhook está disponible en Workflows, lo que permite que flujos conversacionales sean disparados o reanudados por eventos externos.

Consideraciones para Workflows

Nuevas ejecuciones en Workflows

Para iniciar una nueva ejecución de un Workflow vía webhook, el request debe incluir el identificador del usuario (por ejemplo, el número de teléfono en WhatsApp). Esto es necesario para que el Workflow pueda enviar mensajes al usuario a través del canal correspondiente.

curl -X POST https://brain.jelou.ai/v1/webhook/{webhookId} \
  -H "Content-Type: application/json" \
  -d '{"phone": "+593999999999", "evento": "recordatorio"}'

Reanudar ejecuciones en Workflows

Para reanudar una ejecución existente, solo se necesita el executionId. El sistema ya tiene el contexto del usuario desde la ejecución original.

Restricciones de plataforma

En plataformas como WhatsApp, si no hay una sesión activa (ventana de 24 horas) entre el usuario y el bot, el webhook no podrá enviar mensajes directamente. En estos casos, puedes usar un nodo HSM dentro del flujo para enviar una plantilla aprobada que reabre la ventana conversacional.

Versionamiento

El webhook siempre ejecuta la última versión publicada del Workflow. Si hay más de un bot del mismo canal conectado al proyecto, se utiliza el más reciente.

Herencia en workflows hijos

Cuando un Workflow hijo hereda webhooks de su Workflow padre, si el Workflow hijo recibe un request, este sobrescribe los datos del webhook del flujo padre. La data de $webhook se propaga a ejecuciones hijas (nodos Workflow internos).

Testing (Draft)

Para probar el webhook durante el desarrollo (antes de publicar), el nodo genera una URL de pruebas con el sufijo /test:

# URL de producción
https://brain.jelou.ai/v1/webhook/{webhookId}

# URL de pruebas (draft)
https://brain.jelou.ai/v1/webhook/{webhookId}/test

La URL /test ejecuta el draft actual del workflow, permitiéndote iterar sin afectar la versión publicada.

En Workflows, el testing del draft se realiza a través del Workflow Tester. Los parámetros del usuario configurados en el Workflow Tester también aplican cuando se invoca el webhook en modo test.

Retrocompatibilidad

Los webhooks creados antes de esta actualización siguen funcionando sin cambios. Las mejoras aplican solo hacia adelante:

Webhooks existentes conservan su configuración legacy, incluyendo el campo “variable” que guardaba la data en $context.
Webhooks nuevos siempre guardan la información en la nueva entidad $webhook, lo que ofrece una estructura más rica y consistente.

Para webhooks legacy que tenían configurada una variable de contexto, el componente de configuración de variable se seguirá mostrando por retrocompatibilidad. En webhooks nuevos, este campo no aparece ya que la data siempre se almacena en $webhook.

Casos de uso comunes

Notificaciones de pago

Recibe confirmaciones de pasarelas como Stripe o MercadoPago y reanuda el flujo de compra.

Integraciones CRM

Dispara flujos automatizados cuando se crea o actualiza un registro en tu CRM.

Eventos de e-commerce

Procesa eventos como abandono de carrito, envío de pedido o devolución.

Automatizaciones IoT

Recibe datos de sensores o dispositivos para disparar flujos de alerta o procesamiento.

Empezando

Agentes IA

Nodos

Variables

Mensajería Outbound

Gestión

Marketplace

Canales

Configuración

Facturación

Modos de operación

Iniciar nueva ejecución

Reanudar ejecución existente

Configuración

Nombre de la variable

Método HTTP

Reanudar múltiples veces (oneTimeOnly)

Variable `$webhook`

Ejemplo de uso en el flujo

Webhook en Workflows

Consideraciones para Workflows

Testing (Draft)

Retrocompatibilidad

Casos de uso comunes

Notificaciones de pago

Integraciones CRM

Eventos de e-commerce

Automatizaciones IoT

​Modos de operación

​Iniciar nueva ejecución

​Reanudar ejecución existente

​Configuración

​Nombre de la variable

​Método HTTP

​Reanudar múltiples veces (oneTimeOnly)

​Variable $webhook

​Ejemplo de uso en el flujo

​Webhook en Workflows

​Consideraciones para Workflows

​Testing (Draft)

​Retrocompatibilidad

​Casos de uso comunes

Notificaciones de pago

Integraciones CRM

Eventos de e-commerce

Automatizaciones IoT

Modos de operación

Iniciar nueva ejecución

Reanudar ejecución existente

Configuración

Nombre de la variable

Método HTTP

Reanudar múltiples veces (oneTimeOnly)

Variable `$webhook`

Ejemplo de uso en el flujo

Webhook en Workflows

Consideraciones para Workflows

Testing (Draft)

Retrocompatibilidad

Casos de uso comunes