DoubleX AgentesDocs

Guías › Integración

Webhooks

Ejecuta un agente cuando otro sistema llame a una dirección, sin clave de API y sin esperar la respuesta.

Un disparador de tipo webhook le da al agente una dirección propia. Cualquier sistema que pueda hacer un POST ejecuta el agente: un formulario del sitio, el CRM, Stripe, GitHub, un job programado. El cuerpo de la solicitud se convierte en el contexto de la tarea.

1. Crea el disparador#

Elige una de estas formas:

  • En la pantalla: abre el agente, ve a Disparadores › Agregar disparador › Webhook, ponle un nombre y escribe lo que debe hacer el agente.
  • En la CLI:
Terminal
doublex triggers create agt_8f3a2b1c9d0e --name "Nuevo lead del sitio" --webhook \
  --prompt "Llegó un lead: {{nombre}} ({{email}}). Investiga la empresa {{empresa}} y envía un resumen al Slack de ventas."
  • En la API: POST /api/triggers con "type": "webhook" (consulta Disparadores).

La respuesta trae la dirección y el secreto del webhook:

trg_4c1e9a7b2d5f
Dirección del webhook: https://doublex.ai/api/webhooks/trg_4c1e9a7b2d5f
Envía el secreto en el encabezado x-webhook-secret: 3f9a…c21e

2. Llama a la dirección#

Envía el secreto en el encabezado x-webhook-secret:

Terminal
curl -X POST https://doublex.ai/api/webhooks/trg_4c1e9a7b2d5f \
  -H "x-webhook-secret: $WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Ana Souza", "email": "[email protected]", "empresa": "Empresa SA"}'
JSON
{ "accepted": true }

El agente empieza en ese momento, en segundo plano. La respuesta 202 no trae el resultado: sigue la ejecución en la pantalla Tareas (origen Webhook) o con doublex sessions list --agent <id>. Si necesitas el resultado en otro sistema, pide en el prompt que el agente lo entregue por un conector (Slack, correo, hoja de cálculo, base de datos).

Cómo llega el cuerpo al agente#

CuerpoQué recibe el agente
JSON, y el prompt menciona campos como {{email}} o {{cliente.nombre}}El prompt con los campos completados. {{__RAW_JSON__}} inserta el JSON completo.
JSON, y el prompt no menciona ningún campoEl prompt, seguido de los datos recibidos en JSON.
Texto, formulario u otro formatoEl prompt, seguido del texto recibido.
Disparador con Enviar el JSON sin procesar en lugar de un prompt activado (passRawData)Solo el JSON recibido, sin prompt.

El cuerpo puede tener hasta 200.000 caracteres; lo que pase de eso se corta.

Respuestas#

EstadoCuándo
202Aceptado. El agente se está ejecutando.
404Disparador inexistente, secreto incorrecto o disparador que no es webhook. La respuesta es la misma en los tres casos, a propósito.
409El disparador está desactivado, o la ejecución anterior todavía no terminó (vuelve a intentarlo en unos instantes).
402La empresa no tiene un plan activo (plan_required) o se quedó sin créditos (no_credits), o el agente alcanzó su presupuesto del mes (agent_budget). El evento no se ejecuta; vuelve a enviarlo más tarde.
503El agente no tiene un modelo de IA disponible.

Quién paga y con qué cuenta#

  • El agente se ejecuta con la cuenta de quien creó el disparador: usa los conectores y los permisos de esa persona.
  • El consumo sale de los créditos de la organización. Si los créditos se acaban, el webhook sigue respondiendo 202, pero la tarea falla y aparece como Falló en Tareas.

Ejemplos de uso#

  • Formulario del sitio → calificación de leads: el formulario llama al webhook, y el agente investiga la empresa, la registra en el CRM y avisa al vendedor.
  • Pago confirmado → onboarding: el proveedor de pagos llama al webhook, y el agente envía el correo de bienvenida y crea la carpeta del cliente en Drive.
  • Error en producción → triaje: el monitoreo llama al webhook, y el agente lee el error, busca el historial en el Brain y abre un resumen para el equipo.