GloopAPI-Integrationsleitfaden
Webhooks verarbeiten
Signaturprüfung, Wiederholung und Benachrichtigungskonfiguration.
Webhook-Benachrichtigungen werden derzeit nach Abrechnung und Erreichen eines Endzustands normaler Videoaufgaben verwendet. Daraus folgt keine gleichartige Abonnementfunktion für synchrone Bilder, Sprache oder persistente Arbeitsbereiche. Benachrichtigungen enthalten weder Prompts noch Ergebnis-URLs oder rohe Dienstfehler.
Konfiguration und Abonnement
Erstellen Sie unter Konto-Webhooks einen HTTPS-Empfangsendpunkt und speichern Sie das einmalig angezeigte Signatur-secret. Verwaltungsaktionen nutzen die angemeldete Sitzung, nicht die öffentliche Bearer-API; secret und API Key sind verschieden. Übergeben Sie bei Videoanfragen eine aktivierte webhook_endpoint_id desselben Kontos. Beliebige Callback-URLs sind unzulässig. Dieses Feld gehört zur idempotenten Eingabe und darf bei Wiederholungen nicht geändert werden.
Signaturprüfung und Deduplizierung
{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}
Ereignistypen sind video.succeeded, video.failed oder video.cancelled. Bewahren Sie die ursprünglichen Anfragebytes auf und prüfen Sie Webhook-Id, Webhook-Timestamp und Webhook-Signature. Die Signatur lautet v1=<hex>. HMAC-SHA256 verwendet die secret-Zeichenfolge als Schlüssel; die Nachricht verbindet Ereignis-ID, Unix-Zeitstempel in Sekunden und rohen body mit zwei Zeilenumbrüchen, ohne abschließenden Zeilenumbruch:
import hashlib, hmac
message = event_id.encode() + b"\n" + timestamp.encode() + b"\n" + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(received_hex, expected)
Begrenzen Sie die Anfragegröße und verwerfen Sie fehlende oder doppelte Header sowie unbekannte Signaturversionen. Prüfen Sie die Uhrabweichung (empfohlen höchstens 5 Minuten), parsen Sie JSON erst nach erfolgreicher Signaturprüfung und stellen Sie sicher, dass die id im body Webhook-Id entspricht. Das Beispiel berechnet nur den Signaturvergleich; der Empfänger muss zusätzlich alle genannten Prüfungen durchführen.
Speichern Sie das Ereignis zuverlässig dauerhaft oder schließen Sie die idempotente Verarbeitung ab, bevor Sie 2xx zurückgeben. Deduplizieren Sie anhand der stabilen event ID. Bei Wiederholungen bleiben body und ID gleich, während Zeitstempel und Signatur erneuert werden. Fragen Sie nach Ereigniseingang Aufgabe und Ergebnis mit der ursprünglichen Key ab. Die Benachrichtigung selbst berechtigt nicht zum Ergebnisdownload.
Wiederholungen und Rotation
Netzwerkfehler, 408, 429 und 5xx führen automatisch zu Wiederholungen mit Wartezeiten. Nur 2xx gilt als Erfolg; Weiterleitungen werden nicht verfolgt, andere 4xx nicht automatisch wiederholt. Es erfolgen höchstens 12 Versuche innerhalb von maximal 24 Stunden. Prüfen Sie danach im Konto und veranlassen Sie einen erneuten Versand ausdrücklich. Dieser versendet nur die Benachrichtigung erneut, ohne neue Generierung oder Gebühren.
Endpunktänderungen oder Schlüsselrotation erhöhen die Version und pausieren alte ausstehende Zustellungen. Erst ein ausdrücklicher Neuversand verwendet aktuelle Adresse und Schlüssel. Deaktivieren verhindert neue Versuche, kann bereits gesendete Anfragen aber nicht zurückholen. Aktualisieren Sie nach einer Rotation auch den Empfänger. Den Zusammenhang zwischen Status und Abrechnung erklärt Asynchrone Aufgaben und Idempotenz.