API-Schlüssel und Webhooks
So binden Sie Agile Monitoring über die REST-API und Webhooks an Ihre eigenen Systeme an.
Wo Sie alles finden
Öffnen Sie Einstellungen › Entwickler. Dort verwalten Sie API-Schlüssel, Webhooks, verbundene Apps und KI-Assistenten und sehen das Protokoll der API-Anfragen. Die API-Dokumentation finden Sie unter https://monitor.agiledeveloper.de/docs, die Beschreibung im OpenAPI-Format unter /api/openapi.json.
Die REST-API unter /api/v1/ kann alles, was auch die Oberfläche kann.
API-Schlüssel oder Projekt-Schlüssel?
- Der Projekt-Schlüssel in der DSN erlaubt nur das Senden von Ereignissen und darf öffentlich im Browser stehen.
- Ein API-Schlüssel liest und ändert Daten Ihres Arbeitsbereichs. Er ist geheim und gehört nie in Browser-Code.
API-Schlüssel anlegen
- Wählen Sie unter Einstellungen › Entwickler den Bereich API-Schlüssel und legen Sie einen Schlüssel an.
- Geben Sie einen Namen ein, zum Beispiel „CI Deploy“.
- Wählen Sie nur die Bereiche, die Ihre Integration braucht.
- Kopieren Sie den Schlüssel sofort. Er wird nur einmal angezeigt.
Schlüssel beginnen mit agile_monitor_. Senden Sie ihn im Kopf Authorization: Bearer agile_monitor_…. Ein Schlüssel handelt nie mit mehr Rechten als Ihre Rolle.
Bereiche
| Bereich | Erlaubt |
|---|---|
| projekte:lesen, projekte:verwalten | Projekte lesen bzw. anlegen und ändern |
| issues:lesen, issues:bearbeiten | Issues lesen bzw. Status, Zuweisung und Kommentare ändern |
| ereignisse:lesen | einzelne Ereignisse mit Stacktrace lesen |
| uptime:lesen, uptime:verwalten | Monitore und Vorfälle lesen bzw. verwalten |
| heartbeats:lesen, heartbeats:verwalten | Heartbeats lesen bzw. verwalten |
| statusseiten:verwalten | Statusseiten und Meldungen pflegen |
| alarme:verwalten | Alarmregeln und Kanäle pflegen |
| ki:nutzen | KI-Analysen starten und Fragen stellen |
| releases:schreiben | Releases und Deploys melden |
| team:… | Team lesen bzw. verwalten |
| webhooks:verwalten | Webhooks anlegen und Zustellungen lesen |
| abrechnung:… | Tarif und Kontingent lesen bzw. verwalten |
Beispiel: Deploy aus der CI melden
Melden Sie bei jedem Deploy ein Release. Dann zeigt Agile Monitoring, welche Fehler seit diesem Deploy neu sind. Den genauen Endpunkt und die Felder finden Sie in der API-Dokumentation unter dem Abschnitt Releases. Hinweise: https://monitor.agiledeveloper.de/docs/einrichten#releases
Webhooks anlegen
Webhooks gibt es ab dem Tarif Starter.
- Wählen Sie unter Einstellungen › Entwickler den Bereich Webhooks und legen Sie einen Webhook an.
- Geben Sie eine HTTPS-Adresse ein und wählen Sie die Ereignisse.
- Kopieren Sie das Signatur-Geheimnis. Es wird nur jetzt angezeigt.
- Senden Sie mit Testen ein Probe-Ereignis.
Ereignisse
| Ereignis | Bedeutung |
|---|---|
| issue.created | neues Issue |
| issue.regressed | Rückfall eines erledigten Issues |
| issue.resolved | Issue erledigt |
| issue.assigned | Issue zugewiesen |
| monitor.down / monitor.up | Monitor ausgefallen bzw. wieder erreichbar |
| heartbeat.missed / heartbeat.failed | Heartbeat verpasst bzw. fehlgeschlagen |
| quota.warning / quota.exhausted | Kontingent zu 80 % bzw. 100 % genutzt |
| analysis.completed | KI-Analyse fertig |
| subscription.changed | Tarif geändert |
Signatur prüfen
Jedes Ereignis kommt per POST mit JSON. Die Signatur steht im Kopf Agile-Signature. Sie ist ein HMAC-SHA256 mit Ihrem Signatur-Geheimnis. Prüfen Sie sie, bevor Sie ein Ereignis verarbeiten. Antwortet Ihre Adresse nicht mit einem Status von 200 bis 299, versuchen wir es mehrfach erneut.
Protokoll
Im Protokoll unter Einstellungen › Entwickler sehen Sie Ihre API-Anfragen mit Methode, Pfad, Status und Dauer. Inhalte werden nicht protokolliert.