Guía de integración GloopAPI
Consumo de webhooks
Verificación de firmas, repetición y configuración de notificaciones.
Actualmente los webhooks notifican cuando las tareas ordinarias de vídeo se liquidan y llegan a un estado terminal. No supongas que imágenes síncronas, voz o espacios persistentes tienen la misma suscripción. Las notificaciones no incluyen prompts, URL de resultados ni errores originales del servicio.
Configuración y suscripción
Crea un receptor HTTPS en Webhooks de la cuenta y guarda el secreto de firma que se muestra una sola vez. La gestión usa la sesión iniciada, no la API Bearer pública; el secreto es distinto de la clave de API. Al solicitar vídeos, envía un webhook_endpoint_id habilitado de la misma cuenta; no se admiten URL de callback arbitrarias. El campo forma parte de la entrada idempotente y no puede cambiarse al repetir.
Verificación de firma y deduplicación
{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}
Los tipos de evento son video.succeeded, video.failed o video.cancelled. Conserva los bytes originales y valida Webhook-Id, Webhook-Timestamp y Webhook-Signature. La firma es v1=<hex>; HMAC-SHA256 usa la cadena del secreto como clave. El mensaje concatena ID de evento, tiempo Unix en segundos y cuerpo original con dos saltos de línea, sin salto final:
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 el tamaño, rechaza encabezados ausentes o duplicados y versiones desconocidas de firma, y verifica la desviación del reloj (se recomiendan como máximo 5 minutos). Analiza JSON solo tras verificar la firma y confirma que id del cuerpo coincida con Webhook-Id. El ejemplo solo calcula y compara firmas; el receptor debe hacer también estas comprobaciones.
Guarda el evento de forma fiable o completa el procesamiento idempotente antes de devolver 2xx. Deduplica por el ID estable del evento. Los reintentos conservan cuerpo e ID y actualizan tiempo y firma. Tras recibir el evento, consulta tarea y resultado con la clave original; la notificación no es una credencial de descarga.
Reintentos y rotación
Los errores de red, 408, 429 y 5xx activan espera progresiva automática. Solo 2xx cuenta como éxito; no se siguen redirecciones y otros 4xx no se reintentan automáticamente. Se realizan como máximo 12 intentos durante no más de 24 horas; después revisa en tu cuenta y reenvía explícitamente. Reenviar solo vuelve a entregar la notificación; no regenera ni cobra de nuevo.
Actualizar el endpoint o rotar su secreto incrementa la versión y pausa entregas antiguas pendientes; solo el reenvío explícito usa la dirección y secreto actuales. Desactivar impide nuevos intentos pero no retira solicitudes ya enviadas. Actualiza también el receptor al rotar. Consulta la relación entre estados y liquidación en Tareas asíncronas e idempotencia.