Guia de webhooks do AgentVera

O que um webhook faz

Cada webhook recebe uma URL secreta. Para uma requisição a essa URL, o AgentVera pode:

• Abrir um card de kanban no quadro e na coluna que você escolher, com labels se quiser.
• Criar uma tarefa de agente: Claude ou Codex, rodando no seu Runner ou no app desktop que está com o projeto do card aberto.

Quando o agente termina o turno, um resumo do resultado é escrito no card como comentário interno de “AgentVera”. Acompanhe as tarefas ao vivo em app.agentvera.dev/tasks.

Como criar um webhook

Donos e admins da organização criam webhooks. Em app.agentvera.dev/webhooks, clique em “Yeni webhook” (novo webhook) e siga estes passos:

1. Dê um nome ao webhook.
2. Ação de card: escolha o quadro e a coluna onde o card será aberto.
3. Ação de tarefa: escolha o tipo de agente (Claude ou Codex) e o destino. O destino é um Runner específico (opcionalmente com uma pasta de trabalho) ou “Proje” (projeto), ou seja, o app desktop que está com o projeto do card aberto. Tarefas de projeto sempre ficam ligadas a um card.
4. Template: escreva o título do card, a descrição e o prompt do agente com placeholders {{…}}.
5. Filtro (opcional): processe só certas requisições.
6. Assinatura (recomendado): escolha a verificação do GitHub ou HMAC-SHA256 genérica.
7. Salve. A URL do webhook e o segredo de assinatura aparecem só uma vez; copie os dois.

Você pode renovar a URL ou o segredo depois; a URL antiga para de funcionar na hora.

Templates e placeholders

Os placeholders leem valores da requisição recebida:

• {{body.issue.title}}: campos do corpo JSON, como caminho com pontos. Use números para itens de array: {{body.commits.0.id}}.
• {{headers.x-github-event}}: cabeçalhos da requisição, em minúsculas.
• {{query.foo}}: parâmetros de query da URL.

Um valor ausente fica vazio; objetos são inseridos como JSON. Espaços em branco no título do card viram espaços simples e o título é limitado a 300 caracteres. A descrição do card é sanitizada; o prompt vai ao agente exatamente como foi escrito.

Filtro

Um filtro exige que um valor da requisição (caminho) seja igual a um valor dado ou esteja entre os valores que você permite. Por exemplo, para processar só issues do GitHub recém-abertas, defina o caminho como body.action e o valor como opened. Requisições que não batem são registradas como “ignored” e não abrem card nem tarefa.

Verificação de assinatura

• GitHub: o cabeçalho X-Hub-Signature-256 é verificado com o segredo de assinatura.
• HMAC-SHA256 genérica: a assinatura hexadecimal do corpo é esperada num cabeçalho que você define; o prefixo sha256= também é aceito.

Sempre use assinatura quando a origem suportar. Para origens que não assinam, a segurança depende da URL secreta; renove-a se vazar.

Exemplo: tarefas a partir de issues do GitHub

1. No repositório do GitHub, vá em Settings → Webhooks → Add webhook.
2. Informe a URL do webhook do AgentVera como Payload URL, application/json como Content type e o segredo de assinatura como Secret.
3. Escolha o evento “Issues” e salve.

O template no 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}}

Investigue este bug, corrija e rode os testes.

Sentry e outras origens JSON

Aponte qualquer serviço para a URL do webhook. Se a origem pode assinar, use HMAC-SHA256 genérica; se não, conte com a URL secreta. Mapeie no template, com placeholders, os campos que a origem envia. Para testar a partir do seu próprio sistema:

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

Requisições, respostas e limites

• Só POST; o corpo é JSON ou form-encoded, até 1 MB.
• 60 requisições por minuto por webhook, 600 por minuto por IP.
• 202: aceita (requisições ignoradas pelo filtro também recebem 202).
• 401: assinatura inválida.
• 403: o plano da organização não inclui webhooks.
• 404: URL errada, webhook desativado ou organização suspensa (todos recebem a mesma resposta).
• 413: corpo grande demais. 429: limite de taxa atingido.

Entregas e tarefas

• Toda requisição é registrada nas entregas do webhook com um status (ok, ignored, rejected ou failed) e se um card ou tarefa foi criado.
• O conteúdo da requisição (corpo, cabeçalhos e query; sem os cabeçalhos Authorization, cookie e de assinatura) fica guardado por 7 dias e pode ser reprocessado com o template atual nesse período, o que ajuda depois de corrigir um template. Depois disso, o conteúdo é apagado e o resumo fica.
• app.agentvera.dev/tasks mostra as tarefas ao vivo: na fila, pegas, rodando, concluídas ou com falha. Admins podem cancelar tarefas.
• Se o Runner estiver offline, a tarefa espera na fila e é enviada quando o runner se conectar. Uma tarefa que fica 30 minutos sem progresso volta para a fila uma vez; na segunda, é marcada como falha.

Segurança

O conteúdo do webhook entra no prompt do agente do jeito que chega. Qualquer pessoa que possa escrever uma issue num repositório poderia tentar dar instruções ao agente.

• Conecte só origens e repositórios em que você confia.
• Use filtros para restringir quais requisições são processadas.
• No Runner, use roots para limitar as pastas que os agentes alcançam.
• Sempre use assinatura quando a origem suportar; a URL é um segredo, renove-a se vazar.
• O conteúdo das requisições nunca é gravado em logs; a parte secreta da URL é ocultada nos logs.