Webhooks
Subtitling and dubbing are asynchronous. Instead of polling for status, register a URL: Kooma calls it as soon as the job finishes.
Register an endpoint
curl -X POST https://api.kooma.ai/v1/webhooks \
-H "Authorization: Bearer sk-intermo-..." \
-H "Content-Type: application/json" \
-d '{"url":"https://exemple.com/kooma","events":["subtitle.completed","dub.completed"]}'
The response contains a secret (whsec_…) used to verify the signature. It is never returned again: keep it like an API key.
Events
| Event | Triggered when |
|---|---|
subtitle.completed | a subtitling job has finished |
subtitle.failed | a subtitling job has failed |
dub.completed | a dubbing job has finished |
dub.failed | a dubbing job has failed |
An empty events means "all events".
Shape of a delivery
POST https://exemple.com/kooma
X-Kooma-Event: subtitle.completed
X-Kooma-Signature: t=1787525424,v1=5a3f...
{"event":"subtitle.completed","created":1787525424,
"data":{"job_id":"a1b2c3","status":"done","product":"subtitle",
"language":"bam_Latn","n_segments":184}}
Verifying the signature
The signature is an HMAC-SHA256 computed over <horodatage>.<corps brut> with your secret. Compare in constant time, and reject a timestamp that is too old: this is what prevents a captured delivery from being replayed.
import hmac, hashlib, time
def verifier(corps: bytes, entete: str, secret: str, tolerance=300) -> bool:
parts = dict(p.split("=", 1) for p in entete.split(","))
if abs(time.time() - int(parts["t"])) > tolerance:
return False
attendu = hmac.new(secret.encode(), f"{parts['t']}.".encode() + corps,
hashlib.sha256).hexdigest()
return hmac.compare_digest(attendu, parts["v1"])
Retries
Kooma expects a 2xx within 10 seconds. Otherwise the delivery is retried 3 times (immediately, then after 5 s, then after 25 s). After 10 consecutive failures, the endpoint is disabled: re-enable it from the console once your service is back.
Acknowledge immediately and do the work in the background. Long processing inside the handler causes a timeout, therefore a retry, therefore a duplicate.
What Kooma rejects
The URL must use https and point to a public. Loopback, private, link-local and reserved addresses are rejected — otherwise a webhook would let anyone probe an internal network from our servers.
Delivery log
If nothing arrives, look at what Kooma actually attempted and what your server replied:
curl https://api.kooma.ai/v1/webhooks/<id>/deliveries \
-H "Authorization: Bearer sk-intermo-..."
And to exercise your integration without waiting for a real job: POST /v1/webhooks/<id>/test.