Skip to content

Webhooks

Los webhooks te permiten activar equipos de agentes desde sistemas externos mediante HTTP. Define una plantilla de prompt con variables, asegurala con un token, y llama al endpoint desde pipelines CI/CD, alertas de monitoreo, integraciones de terceros o cualquier sistema que pueda hacer peticiones HTTP.

Casos de Uso

  • CI/CD: Activa un equipo de revision de codigo cuando se abre un pull request, o ejecuta una lista de verificacion de despliegue despues de un merge.
  • Alertas: Enruta alertas de monitoreo (PagerDuty, Grafana, Datadog) a un equipo de agentes SRE para triaje automatizado.
  • Integraciones de terceros: Conecta eventos de CRM, envios de formularios o comandos slash de Slack a equipos de agentes especializados.
  • Disparadores externos programados: Usa programadores externos (GitHub Actions cron, AWS EventBridge) para activar flujos de trabajo de agentes con contexto dinamico.

Como Funcionan los Webhooks

Cuando se activa un webhook, AgentCrew ejecuta los siguientes pasos:

  1. Autenticar la solicitud entrante verificando el token en la URL.
  2. Renderizar la plantilla de prompt reemplazando {{variables}} con los valores del cuerpo de la solicitud.
  3. Enviar el prompt renderizado al lider del equipo via NATS.
  4. Responder inmediatamente (fire-and-forget) o esperar la respuesta del agente (modo esperar respuesta).
  5. Registrar la ejecucion en el historial del webhook.

A diferencia de las tareas programadas, los webhooks no despliegan ni liberan equipos. El equipo destino debe estar ya en ejecucion cuando se activa el webhook. Este diseno mantiene las respuestas rapidas y evita la latencia de inicio de contenedores.

Crear un Webhook

Navega a la seccion Webhooks en la barra lateral y haz clic en New Webhook. El constructor de webhooks te guia a traves de:

  1. Nombre: Un nombre descriptivo para el webhook (por ejemplo, "Disparador de Review de PR", "Triaje de Alertas").
  2. Equipo: Selecciona que equipo de agentes recibira el prompt. El equipo debe existir previamente.
  3. Plantilla de Prompt: La instruccion enviada al lider del equipo cuando se activa el webhook. Usa marcadores {{nombre_variable}} para valores dinamicos que se reemplazaran en el momento de la activacion.
  4. Timeout: Tiempo maximo de espera para una respuesta en el modo esperar respuesta. Por defecto usa la configuracion global WEBHOOK_TIMEOUT.
  5. Max Concurrente: Numero maximo de ejecuciones simultaneas para este webhook. Las activaciones adicionales se encolan.

Despues de la creacion, se genera un token unico que se muestra una sola vez. Copialo y guardalo de forma segura — no se puede recuperar despues.

Activar un Webhook

Envia una solicitud POST al endpoint de activacion con el token del webhook: 

POST /webhook/trigger/:token

El cuerpo de la solicitud debe ser JSON con un objeto variables que contenga los pares clave-valor que correspondan a los marcadores de tu plantilla de prompt: 

{
  "variables": {
    "pr_title": "Add user authentication",
    "pr_url": "https://github.com/org/repo/pull/42",
    "author": "alice"
  }
}

Modo Fire-and-Forget (Por Defecto)

Por defecto, el webhook responde inmediatamente con una respuesta 202 Accepted, confirmando que el prompt fue encolado para procesamiento: 

curl -X POST https://tu-agentcrew/webhook/trigger/whk_abc123def456 \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "alert_name": "High CPU Usage",
      "service": "api-server",
      "severity": "warning"
    }
  }'

# Respuesta: 202 Accepted
# {  "status": "accepted", "run_id": "..." }

Modo Esperar Respuesta

Agrega ?wait=true a la URL de activacion para esperar la respuesta del equipo de agentes. La solicitud se bloquea hasta que el agente responde o se alcanza el timeout: 

curl -X POST "https://tu-agentcrew/webhook/trigger/whk_abc123def456?wait=true" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "pr_title": "Add user authentication",
      "pr_url": "https://github.com/org/repo/pull/42"
    }
  }'

# Respuesta: 200 OK (con respuesta del agente)
# {  "status": "success", "response": "...", "run_id": "..." }

# O: 408 Request Timeout (si se alcanza el timeout)
# {  "status": "timeout", "run_id": "..." }

Seguridad del Token

  • Los tokens usan el prefijo whk_ para facil identificacion en logs y configuracion.
  • Los tokens se almacenan con hash SHA-256 — el token en texto plano nunca se persiste en la base de datos.
  • El token en texto plano se muestra solo una vez en el momento de la creacion. Si se pierde, debes regenerar un nuevo token.

Gestionar Webhooks

Regenerar Tokens

Si un token es comprometido o se pierde, puedes regenerarlo desde la pagina de detalle del webhook. El token anterior se invalida inmediatamente y se muestra uno nuevo una sola vez.

Historial de Ejecuciones

Cada webhook mantiene un historial paginado de todas las ejecuciones. Para cada ejecucion puedes ver:

  • Estado: exitoso, error o timeout.
  • Inicio / Fin: Marcas de tiempo en tu zona horaria local.
  • Duracion: Cuanto tiempo tomo la ejecucion.
  • Variables: Las variables enviadas en la solicitud de activacion.
  • Conversacion: Expande cualquier ejecucion para ver el prompt renderizado y la respuesta del agente.

Activar / Desactivar

Cada webhook tiene un interruptor para activarlo o desactivarlo. Los webhooks desactivados devuelven 404 Not Found cuando se activan, previniendo ejecuciones accidentales.

Editar

Haz clic en cualquier webhook para editar su nombre, plantilla de prompt, equipo, timeout o configuracion de concurrencia maxima. Los cambios toman efecto inmediatamente para las activaciones posteriores.

Eliminar

Eliminar un webhook lo borra junto con todo su historial de ejecuciones de forma permanente. El token se invalida inmediatamente.

Configuracion

El comportamiento de los webhooks se puede ajustar con variables de entorno:

Variable Defecto Descripcion
WEBHOOK_MAX_CONCURRENT 20 Numero maximo global de ejecuciones de webhooks que pueden ejecutarse simultaneamente. Las activaciones excedentes se encolan. Tambien se puede sobreescribir por webhook.

Notas de Arquitectura

  • El motor de webhooks se ejecuta como parte del proceso del servidor API — no se necesita un servicio separado.
  • Los webhooks requieren que el equipo destino este ya en ejecucion. A diferencia de las tareas programadas, no despliegan ni liberan equipos.
  • Procesamiento FIFO por equipo: Cuando multiples webhooks (o webhooks y mensajes de chat) apuntan al mismo equipo, los mensajes se encolan y procesan uno a la vez en orden de llegada. Un ID de correlacion asegura que cada llamador reciba la respuesta correcta, usando el mismo mecanismo de correlacion FIFO de NATS que las tareas programadas.
  • La concurrencia se controla en dos niveles: la configuracion global WEBHOOK_MAX_CONCURRENT y la configuracion por webhook max_concurrent.

Siguientes Pasos

  • Tareas Programadas: Automatiza tareas recurrentes con programaciones basadas en cron que despliegan y liberan equipos automaticamente.
  • Configuracion: Revisa todas las variables de entorno incluyendo las configuraciones especificas de webhooks.
  • Arquitectura: Comprende como los webhooks encajan en el diseno general del sistema.