GloopAPI integration guide
Consuming webhooks
Signature verification, replay, and notification configuration.
Webhook notifications currently apply after ordinary video tasks settle and reach a terminal state. Do not assume synchronous images, speech, or persistent workspaces have the same subscription capabilities. Notifications do not contain prompts, result URLs, or internal diagnostic details.
Configuration and subscription
Create an HTTPS receiving endpoint in Account Webhooks and save the signing secret shown once. Management operations use the login session, not the public Bearer API; the secret differs from the API key. Video requests must pass an enabled webhook_endpoint_id on the same account; arbitrary callback URLs are not accepted. This field is part of the idempotent input, so replays cannot switch endpoints.
Signature verification and deduplication
{"id":"evt_example","type":"video.succeeded","created_at":1790000000,"data":{"task_id":"vid_example","status":"succeeded"}}
Event types are video.succeeded, video.failed, or video.cancelled. Retain the raw request bytes and validate Webhook-Id, Webhook-Timestamp, and Webhook-Signature. The signature is v1=<hex>. HMAC-SHA256 uses the secret string as its key; the message concatenates the event ID, Unix timestamp in seconds, and raw body with two newlines and no trailing newline:
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)
Limit request size, reject missing or duplicate headers and unknown signature versions, and check clock skew (at most 5 minutes is recommended). Parse JSON only after successful signature verification, and confirm that the body's id equals Webhook-Id. The example only computes and compares signatures; the receiver must also perform the validations above.
Reliably persist the event or complete idempotent processing before returning 2xx. Deduplicate by the stable event ID. Retries retain the body and ID while updating the timestamp and signature. After receiving an event, query the task/result with the original API key; the notification itself is not a result download credential.
Retries and rotation
Network errors, 408, 429, and 5xx trigger automatic backoff. Only 2xx counts as success. Redirects are not followed, and other 4xx responses are not automatically retried. Delivery is attempted at most 12 times and for no longer than 24 hours; after that, review it in your account and explicitly resend. Resending only redelivers the notification; it does not regenerate content or incur another generation charge.
Updating an endpoint or rotating its secret increments the version and pauses old pending deliveries. Only an explicit resend uses the current address and secret. Disabling prevents new attempts but cannot recall already sent requests; update the receiver when rotating secrets. See Asynchronous tasks and idempotency for the relationship between status and settlement.