API, API-Schlüssel und Webhooks
So steuern Sie Agile Deploy per REST-API und erhalten Ereignisse als signierte Webhooks.
Dokumentation
Die vollständige API-Dokumentation steht unter https://deploy.agiledeveloper.de/docs (REST API v1 mit OpenAPI 3.1). Sie erreichen sie auch über Einstellungen → Entwickler.
API-Schlüssel anlegen
- Öffnen Sie Einstellungen → Entwickler.
- Klicken Sie bei API-Schlüssel auf Neuer Schlüssel.
- Vergeben Sie einen Namen und wählen Sie die Rechte.
- Klicken Sie auf Anlegen und kopieren Sie den Schlüssel. Er wird nur dieses eine Mal angezeigt.
Senden Sie den Schlüssel als Kopfzeile: Authorization: Bearer agile_dp_…
Widerrufen sperrt einen Schlüssel sofort.
Rechte
projekte:lesen: Projekte, Deployments, Build-Logs, Domains und Datenbanken ohne Zugangsdaten lesenprojekte:schreiben: Projekte anlegen, ändern und löschen, Umgebungsvariablen setzen, Git-Verbindungen nutzendeployments:schreiben: deployen, erneut bauen, in Produktion übernehmen, Rollback und Abbrechendomains:schreiben: eigene Domains hinzufügen, prüfen und entfernendatenbanken:schreiben: Datenbanken anlegen, löschen, sichern, wiederherstellen und Zugangsdaten lesenteam:lesen: Team und Mitglieder lesenteam:verwalten: Mitglieder einladen, Rollen und Team ändern (nur Team-Admins)webhooks:verwalten: Webhook-Endpunkte anlegen, löschen und Zustellungen lesenabrechnung:lesen: Tarif, Guthaben, Kontingente und Nutzung lesen
Zahlungen auslösen geht nur in der App.
Grenzen und Hilfen
- Höchstens 120 Anfragen pro Minute.
- Listen liefern 1 bis 200 Einträge je Seite, Standard 50.
- Mit der Kopfzeile
Idempotency-Keyführt eine Wiederholung innerhalb von 24 Stunden die Anfrage nicht erneut aus. - Fehlermeldungen kommen auf Englisch, wenn Sie
Accept-Language: ensenden, sonst auf Deutsch.
Webhooks einrichten
- Klicken Sie unter Einstellungen → Entwickler bei Webhooks auf Neuer Webhook.
- Tragen Sie die Adresse ein. Sie muss mit
https://beginnen. Interne Adressen sind nicht erlaubt. - Wählen Sie die Ereignisse und klicken Sie auf Anlegen.
- Kopieren Sie das Signatur-Geheimnis. Es wird nur einmal angezeigt.
Je Konto sind höchstens 10 Endpunkte möglich. Über das Blitz-Symbol senden Sie einen Test.
Ereignisse
deployment.erstellt, deployment.bereit, deployment.fehler, deployment.blockiert, domain.verifiziert, datenbank.bereit, limit.erreicht, guthaben.niedrig, guthaben.leer, team.beigetreten
Signatur prüfen
Jede Zustellung ist ein POST mit den Kopfzeilen Agile-Signature, Agile-Event und Agile-Delivery. Agile-Signature hat die Form t=<Zeit>,v1=<Signatur>. Die Signatur ist HMAC-SHA256 über <Zeit>.<Inhalt> mit Ihrem Signatur-Geheimnis.
Wiederholungen
Schlägt eine Zustellung fehl, versucht Agile Deploy es nach 1, 5, 30, 120, 360 und 1440 Minuten erneut. Danach gilt sie als fehlgeschlagen. Zustellprotokolle werden nach 30 Tagen gelöscht.