Kooma API
Français API keys Sign up

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 secret is shown only once

The response contains a secret (whsec_…) used to verify the signature. It is never returned again: keep it like an API key.

Events

EventTriggered when
subtitle.completeda subtitling job has finished
subtitle.faileda subtitling job has failed
dub.completeda dubbing job has finished
dub.faileda 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.

Reply fast, process afterwards

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.

↑↓ navigate↵ openesc close