AgentVera-Webhook-Anleitung

Was ein Webhook macht

Jeder Webhook bekommt eine geheime URL. Bei einer Anfrage an diese URL kann AgentVera:

• eine Kanban-Karte auf dem Board und in der Spalte deiner Wahl öffnen, auf Wunsch mit Labels.
• eine Agent-Aufgabe erstellen: Claude oder Codex, entweder auf deinem Runner oder in der Desktop-App, die das Projekt der Karte geöffnet hat.

Wenn der Agent seinen Turn beendet, wird eine Zusammenfassung des Ergebnisses als interner Kommentar von „AgentVera“ auf die Karte geschrieben. Aufgaben verfolgst du live unter app.agentvera.dev/tasks.

Einen Webhook erstellen

Webhooks erstellen Organisationsinhaber und Admins. Klicke unter app.agentvera.dev/webhooks auf „Yeni webhook“ (neuer Webhook) und folge diesen Schritten:

1. Gib dem Webhook einen Namen.
2. Kartenaktion: Wähle das Board und die Spalte, in der die Karte geöffnet wird.
3. Aufgabenaktion: Wähle den Agent-Typ (Claude oder Codex) und das Ziel. Das Ziel ist ein bestimmter Runner (optional mit Arbeitsordner) oder „Proje“ (Projekt), also die Desktop-App, die das Projekt der Karte geöffnet hat. Projektaufgaben sind immer an eine Karte gebunden.
4. Vorlage: Schreibe Kartentitel, Beschreibung und Agent-Prompt mit {{…}}-Platzhaltern.
5. Filter (optional): Verarbeite nur bestimmte Anfragen.
6. Signatur (empfohlen): Wähle die GitHub- oder die generische HMAC-SHA256-Prüfung.
7. Speichern. Die Webhook-URL und das Signaturgeheimnis werden nur einmal angezeigt; kopiere beide.

Du kannst die URL oder das Geheimnis später erneuern; die alte URL funktioniert dann sofort nicht mehr.

Vorlagen und Platzhalter

Platzhalter lesen Werte aus der eingehenden Anfrage:

• {{body.issue.title}}: Felder des JSON-Bodys als Punktpfad. Für Array-Elemente verwendest du Zahlen: {{body.commits.0.id}}.
• {{headers.x-github-event}}: Request-Header, kleingeschrieben.
• {{query.foo}}: Query-Parameter in der URL.

Ein fehlender Wert wird leer; Objekte werden als JSON eingefügt. Leerraum im Kartentitel wird auf einzelne Leerzeichen reduziert, und der Titel ist auf 300 Zeichen begrenzt. Die Kartenbeschreibung wird bereinigt; der Prompt geht genau so an den Agent, wie du ihn geschrieben hast.

Filter

Ein Filter verlangt, dass ein Wert in der Anfrage (Pfad) einem bestimmten Wert entspricht oder einer der erlaubten Werte ist. Für nur neu geöffnete GitHub-Issues setzt du zum Beispiel den Pfad auf body.action und den Wert auf opened. Anfragen, die nicht passen, werden als „ignored“ protokolliert und öffnen weder Karte noch Aufgabe.

Signaturprüfung

• GitHub: Der Header X-Hub-Signature-256 wird mit dem Signaturgeheimnis geprüft.
• Generisches HMAC-SHA256: Die Hex-Signatur des Bodys wird in einem Header erwartet, den du benennst; ein Präfix sha256= wird ebenfalls akzeptiert.

Nutze die Signatur immer, wenn die Quelle sie unterstützt. Bei Quellen, die nicht signieren können, beruht die Sicherheit auf der geheimen URL; erneuere sie, falls sie durchsickert.

Beispiel: Aufgaben aus GitHub-Issues

1. Gehe im GitHub-Repository zu Settings → Webhooks → Add webhook.
2. Trage die AgentVera-Webhook-URL als Payload URL ein, application/json als Content type und das Signaturgeheimnis als Secret.
3. Wähle das Ereignis „Issues“ und speichere.

Die Vorlage in 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}}

Untersuche diesen Bug, behebe ihn und führe die Tests aus.

Sentry und andere JSON-Quellen

Richte einen beliebigen Dienst auf die Webhook-URL aus. Kann die Quelle signieren, nutze generisches HMAC-SHA256; wenn nicht, verlasse dich auf die geheime URL. Ordne die Felder, die die Quelle sendet, per Platzhalter der Vorlage zu. Zum Ausprobieren aus deinem eigenen System:

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

Anfragen, Antworten und Limits

• Nur POST; der Body ist JSON oder formularkodiert, bis zu 1 MB.
• 60 Anfragen pro Minute je Webhook, 600 pro Minute je IP.
• 202: angenommen (auch vom Filter ignorierte Anfragen erhalten 202).
• 401: ungültige Signatur.
• 403: Der Tarif der Organisation enthält keine Webhooks.
• 404: falsche URL, deaktivierter Webhook oder gesperrte Organisation (alle erhalten dieselbe Antwort).
• 413: Body zu groß. 429: Rate-Limit erreicht.

Zustellungen und Aufgaben

• Jede Anfrage wird unter den Zustellungen des Webhooks mit einem Status protokolliert: ok, ignored, rejected oder failed, dazu ob eine Karte oder Aufgabe erstellt wurde.
• Der Inhalt der Anfrage (Body, Header und Query; Authorization-, Cookie- und Signatur-Header ausgenommen) wird 7 Tage aufbewahrt und kann in dieser Zeit mit der aktuellen Vorlage erneut abgespielt werden, was hilft, nachdem du eine Vorlage korrigiert hast. Danach wird der Inhalt gelöscht und die Zusammenfassung bleibt.
• app.agentvera.dev/tasks zeigt Aufgaben live: in der Warteschlange, übernommen, läuft, fertig oder fehlgeschlagen. Admins können Aufgaben abbrechen.
• Ist der Runner offline, wartet die Aufgabe in der Warteschlange und wird gesendet, sobald sich der Runner verbindet. Eine Aufgabe, die 30 Minuten lang keinen Fortschritt macht, kommt einmal zurück in die Warteschlange; beim zweiten Mal wird sie als fehlgeschlagen markiert.

Sicherheit

Der Webhook-Inhalt geht unverändert in den Prompt des Agents. Wer in einem Repository ein Issue schreiben kann, könnte versuchen, den Agent anzuweisen.

• Verbinde nur Quellen und Repositories, denen du vertraust.
• Nutze Filter, um einzuschränken, welche Anfragen verarbeitet werden.
• Begrenze beim Runner mit roots die Ordner, die Agents erreichen können.
• Nutze die Signatur immer, wenn die Quelle sie unterstützt; die URL ist ein Geheimnis, erneuere sie, falls sie durchsickert.
• Anfrageinhalte werden nie in Logs geschrieben; der geheime Teil der URL wird in Logs geschwärzt.