Guía de webhooks de AgentVera

Qué hace un webhook

Cada webhook recibe una URL secreta. Ante una petición a esa URL, AgentVera puede:

• Abrir una tarjeta kanban en el tablero y la columna que elijas, con etiquetas si quieres.
• Crear una tarea de agente: Claude o Codex, ejecutándose en tu Runner o en la app de escritorio que tenga abierto el proyecto de la tarjeta.

Cuando el agente termina su turno, un resumen del resultado se escribe en la tarjeta como comentario interno de “AgentVera”. Sigue las tareas en directo en app.agentvera.dev/tasks.

Crear un webhook

Los propietarios y administradores de la organización crean los webhooks. En app.agentvera.dev/webhooks, haz clic en “Yeni webhook” (nuevo webhook) y sigue estos pasos:

1. Ponle un nombre al webhook.
2. Acción de tarjeta: elige el tablero y la columna donde se abre la tarjeta.
3. Acción de tarea: elige el tipo de agente (Claude o Codex) y el destino. El destino es un Runner concreto (opcionalmente con una carpeta de trabajo) o “Proje” (proyecto), es decir, la app de escritorio que tenga abierto el proyecto de la tarjeta. Las tareas de proyecto siempre están vinculadas a una tarjeta.
4. Plantilla: escribe el título de la tarjeta, la descripción y el prompt del agente con marcadores {{…}}.
5. Filtro (opcional): procesa solo determinadas peticiones.
6. Firma (recomendada): elige la verificación de GitHub o HMAC-SHA256 genérica.
7. Guarda. La URL del webhook y el secreto de firma solo se muestran una vez; copia ambos.

Más adelante puedes rotar la URL o el secreto; la URL antigua deja de funcionar de inmediato.

Plantillas y marcadores

Los marcadores leen valores de la petición entrante:

• {{body.issue.title}}: campos del cuerpo JSON, como ruta con puntos. Usa números para los elementos de un array: {{body.commits.0.id}}.
• {{headers.x-github-event}}: cabeceras de la petición, en minúsculas.
• {{query.foo}}: parámetros de consulta de la URL.

Un valor que falta queda vacío; los objetos se insertan como JSON. Los espacios en blanco del título de la tarjeta se reducen a un solo espacio y el título se limita a 300 caracteres. La descripción de la tarjeta se sanea; el prompt llega al agente exactamente como lo escribiste.

Filtro

Un filtro exige que un valor de la petición (path) sea igual a un valor dado o sea uno de los valores que permites. Por ejemplo, para recibir solo las issues de GitHub recién abiertas, pon como path body.action y como valor opened. Las peticiones que no coinciden se registran como “ignored” y no abren ninguna tarjeta ni tarea.

Verificación de firma

• GitHub: la cabecera X-Hub-Signature-256 se verifica con el secreto de firma.
• HMAC-SHA256 genérica: la firma hexadecimal del cuerpo se espera en una cabecera que tú nombras; también se acepta el prefijo sha256=.

Usa siempre la firma cuando el origen la admita. En los orígenes que no pueden firmar, la seguridad depende de la URL secreta; rótala si se filtra.

Ejemplo: tareas a partir de issues de GitHub

1. En el repositorio de GitHub, ve a Settings → Webhooks → Add webhook.
2. Introduce la URL del webhook de AgentVera como Payload URL, application/json como Content type y el secreto de firma como Secret.
3. Elige el evento “Issues” y guarda.

La plantilla en AgentVera:

Title:       {{body.issue.title}}
Description: {{body.issue.body}}
Filter:      body.action = opened
Prompt:
GitHub issue #{{body.issue.number}}: {{body.issue.title}}

{{body.issue.body}}

Investiga este error, corrígelo y ejecuta las pruebas.

Sentry y otras fuentes JSON

Apunta cualquier servicio a la URL del webhook. Si el origen puede firmar, usa HMAC-SHA256 genérica; si no, confía en la URL secreta. Asigna los campos que envía el origen a la plantilla con marcadores. Para probarlo desde tu propio sistema:

curl -X POST "https://app.agentvera.dev/hooks/<id>/<secret>" \
  -H "content-type: application/json" \
  -d '{"title": "Checkout page returns 500", "detail": "..."}'

Peticiones, respuestas y límites

• Solo POST; el cuerpo es JSON o codificado como formulario, de hasta 1 MB.
• 60 peticiones por minuto por webhook, 600 por minuto por IP.
• 202: aceptada (las peticiones ignoradas por el filtro también reciben 202).
• 401: firma no válida.
• 403: el plan de la organización no incluye webhooks.
• 404: URL incorrecta, webhook desactivado u organización suspendida (todos reciben la misma respuesta).
• 413: cuerpo demasiado grande. 429: límite de frecuencia superado.

Entregas y tareas

• Cada petición se registra en las entregas del webhook con un estado: ok, ignored, rejected o failed, además de si se creó una tarjeta o una tarea.
• El contenido de la petición (cuerpo, cabeceras y consulta; sin las cabeceras Authorization, cookie ni de firma) se conserva 7 días y durante ese tiempo puede reproducirse con la plantilla actual, lo que ayuda después de corregir una plantilla. Pasado ese plazo, el contenido se elimina y el resumen permanece.
• app.agentvera.dev/tasks muestra las tareas en directo: queued, claimed, running, done o failed. Los administradores pueden cancelar tareas.
• Si el Runner está sin conexión, la tarea espera en la cola y se envía cuando el runner se conecta. Una tarea que no avanza durante 30 minutos vuelve a la cola una vez; la segunda vez se marca como fallida.

Seguridad

El contenido del webhook pasa al prompt del agente tal cual. Cualquiera que pueda escribir una issue en un repositorio podría intentar darle instrucciones al agente.

• Conecta solo orígenes y repositorios de confianza.
• Usa filtros para acotar qué peticiones se procesan.
• En Runner, usa roots para limitar las carpetas a las que pueden acceder los agentes.
• Usa siempre la firma cuando el origen la admita; la URL es un secreto, rótala si se filtra.
• El contenido de las peticiones nunca se escribe en los registros; la parte secreta de la URL se oculta en los registros.