Guida all'integrazione GloopAPI
Consumo dei webhook
Verifica delle firme, ripetizioni e configurazione delle notifiche.
Le notifiche Webhook sono attualmente usate dopo l'addebito definitivo e lo stato terminale delle attività video ordinarie. Non presumere che immagini sincrone, voce o aree persistenti offrano gli stessi abbonamenti. Le notifiche non contengono prompt, URL dei risultati o errori grezzi del servizio.
Configurazione e abbonamento
Crea un endpoint HTTPS di ricezione in Webhooks dell'account e conserva il secret di firma mostrato una sola volta. Le operazioni di gestione usano la sessione autenticata, non l'API Bearer pubblica; il secret è diverso dall'API Key. Quando richiedi un video, passa un webhook_endpoint_id attivo dello stesso account; gli URL di callback arbitrari non sono accettati. Questo campo fa parte dell'input idempotente e non può cambiare nelle ripetizioni.
Verifica della firma e deduplicazione
{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}
I tipi di evento sono video.succeeded, video.failed o video.cancelled. Conserva i byte originali della richiesta e verifica Webhook-Id, Webhook-Timestamp e Webhook-Signature. La firma è v1=<hex>; HMAC-SHA256 usa la stringa secret come chiave. Il messaggio concatena ID dell'evento, timestamp Unix in secondi e body originale con due ritorni a capo, senza ritorno a capo finale:
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)
Limita la dimensione della richiesta, rifiuta header mancanti o duplicati e versioni di firma sconosciute. Controlla lo scarto dell'orologio (si consiglia un massimo di 5 minuti), analizza il JSON solo dopo la verifica della firma e assicurati che l'id nel body coincida con Webhook-Id. L'esempio calcola solo il confronto della firma; il ricevitore deve completare anche tutti questi controlli.
Conserva l'evento in modo persistente e affidabile o completa il trattamento idempotente prima di restituire 2xx. Deduplica usando l'event ID stabile; nei nuovi tentativi body e ID restano identici, mentre timestamp e firma cambiano. Dopo la ricezione, interroga attività e risultato con la Key originale. La notifica non è una credenziale per scaricare il risultato.
Nuovi tentativi e rotazione
Errori di rete, 408, 429 e 5xx attivano automaticamente tentativi con attesa progressiva. Solo 2xx conta come successo; i reindirizzamenti non vengono seguiti e gli altri 4xx non vengono riprovati automaticamente. Il limite è 12 tentativi entro 24 ore; successivamente verifica nell'account e richiedi esplicitamente un reinvio. Il reinvio consegna di nuovo soltanto la notifica, senza nuova generazione o addebiti.
L'aggiornamento dell'endpoint o la rotazione della chiave incrementa la versione e sospende le vecchie consegne in attesa. Solo un reinvio esplicito usa indirizzo e chiave correnti. La disattivazione impedisce nuovi tentativi, ma non ritira richieste già inviate; dopo la rotazione aggiorna anche il ricevitore. Per il rapporto tra stato e contabilità, vedi Attività asincrone e idempotenza.