Guia de integração GloopAPI
Consumo de webhooks
Verificação de assinaturas, repetição e configuração de notificações.
Atualmente os webhooks notificam após tarefas comuns de vídeo serem liquidadas e atingirem estado terminal. Não presuma que imagens síncronas, voz ou espaços persistentes tenham a mesma assinatura de notificações. As notificações não incluem prompts, URLs de resultados nem erros brutos do serviço.
Configuração e assinatura
Crie um receptor HTTPS em Webhooks da conta e salve o segredo de assinatura mostrado uma única vez. A gestão usa a sessão autenticada, não a API Bearer pública; o segredo difere da chave de API. Ao solicitar vídeos, envie um webhook_endpoint_id ativado da mesma conta; URLs de callback arbitrárias não são aceitas. O campo integra a entrada idempotente e não pode mudar ao repetir.
Verificação de assinatura e deduplicação
{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}
Os tipos de evento são video.succeeded, video.failed ou video.cancelled. Preserve os bytes originais e valide Webhook-Id, Webhook-Timestamp e Webhook-Signature. A assinatura é v1=<hex>; HMAC-SHA256 usa a string do segredo como chave. A mensagem concatena ID do evento, timestamp Unix em segundos e corpo original com duas quebras de linha, sem quebra 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)
Limite o tamanho, rejeite cabeçalhos ausentes ou duplicados e versões desconhecidas de assinatura, e verifique a diferença de relógio (recomendado no máximo 5 minutos). Analise o JSON apenas após validar a assinatura e confirme que o id do corpo corresponde a Webhook-Id. O exemplo apenas calcula e compara assinaturas; o receptor também deve executar essas verificações.
Persista o evento com segurança ou conclua o processamento idempotente antes de retornar 2xx. Elimine duplicatas pelo ID estável do evento. Novas tentativas preservam corpo e ID, atualizando horário e assinatura. Após receber o evento, consulte tarefa e resultado com a chave original; a notificação não é credencial de download.
Novas tentativas e rotação
Erros de rede, 408, 429 e 5xx acionam espera progressiva automática. Apenas 2xx conta como sucesso; redirecionamentos não são seguidos, e outros 4xx não são repetidos automaticamente. São no máximo 12 tentativas durante até 24 horas; depois confira na conta e reenvie explicitamente. Reenviar apenas entrega a notificação novamente; não regenera nem cobra de novo.
Atualizar o endpoint ou rotacionar o segredo aumenta a versão e pausa entregas antigas pendentes; só o reenvio explícito usa endereço e segredo atuais. Desativar impede novas tentativas, mas não desfaz solicitações já enviadas. Atualize também o receptor ao rotacionar. Consulte a relação entre estados e liquidação em Tarefas assíncronas e idempotência.