Webhooks
Ein Webhook schickt eine HTTP-Anfrage an deine Adresse, sobald in Agile Cut etwas passiert – zum Beispiel wenn ein Export fertig ist. So musst du nicht ständig nachfragen und kannst Automationen direkt anstoßen.
Ereignisse
| Ereignis | Wann |
|---|---|
| export.completed | ein Export ist fertig |
| export.failed | ein Export ist fehlgeschlagen |
| medium.ready | ein hochgeladenes oder importiertes Medium ist aufbereitet und bereit |
| job.completed | ein KI- oder Bearbeitungsauftrag ist fertig |
| job.failed | ein Auftrag ist fehlgeschlagen (es wurden keine Credits berechnet) |
| share.comment | jemand hat auf einem Teilen-Link kommentiert |
| credits.warning | 80 % des Credit-Kontingents sind verbraucht |
| credits.exhausted | das Kontingent ist aufgebraucht |
| subscription.changed | dein Abo hat sich geändert |
Webhook einrichten
- Öffne Einstellungen → Webhooks.
- Klicke auf Neuer Webhook.
- Gib die Ziel-URL ein (HTTPS).
- Wähle die Ereignisse, die du empfangen willst.
- Speichern. Agile Cut zeigt dir das Signatur-Geheimnis an – bewahre es sicher auf.
Webhooks lassen sich auch über die API unter /api/v1/webhooks verwalten.
Aufbau einer Zustellung
Agile Cut schickt eine POST-Anfrage mit JSON. Sie enthält den Ereignisnamen, den Zeitpunkt und die zugehörigen Daten, zum Beispiel beim Export die Export-ID, das Projekt und den Status.
Signatur prüfen
Jede Zustellung ist mit deinem Signatur-Geheimnis signiert. Prüfe die Signatur auf deinem Server, bevor du die Daten verarbeitest – so stellst du sicher, dass die Anfrage wirklich von Agile Cut kommt.
Jede Anfrage trägt diese Header:
| Header | Inhalt |
|---|---|
| Agile-Signature | t=<Unix-Zeit>,v1=<Signatur> |
| Agile-Event | Name des Ereignisses |
| Agile-Delivery | ID der Zustellung |
So prüfst du die Signatur:
- Lies
tundv1aus dem HeaderAgile-Signature. - Bilde den Text
<t>.<roher Anfragekörper>. - Berechne darüber ein HMAC-SHA256 mit deinem Signatur-Geheimnis (hexadezimal).
- Vergleiche das Ergebnis zeitkonstant mit
v1. Verwirf zusätzlich Anfragen, derentzu weit in der Vergangenheit liegt.
Details stehen in der API-Dokumentation unter https://cut.agiledeveloper.de/docs.
Antwort und Wiederholung
- Antworte innerhalb von 10 Sekunden mit einem Statuscode 2xx, sobald du die Nachricht angenommen hast. Längere Verarbeitung erledigst du danach im Hintergrund.
- Bei Fehlern oder Zeitüberschreitung versucht Agile Cut die Zustellung später erneut.
- Die Zustellungen der letzten Zeit samt Antwortcode siehst du beim Webhook unter Einstellungen → Webhooks.
Typische Anwendungen
- Fertigen Export automatisch in deinen Cloud-Speicher oder dein CMS übernehmen.
- Bei
share.commenteine Nachricht an dein Team schicken. - Bei
credits.warningdie Buchhaltung informieren oder Credits nachkaufen.
Push statt Webhook
Willst du nur selbst informiert werden, reichen oft die Push-Benachrichtigungen aufs Handy oder den Desktop (siehe „Agile Cut als App auf dem Handy“).