Centro assistenza / API e webhook

API e webhook

Crea ad dalla tua app e ricevi una notifica quando sono pronti, con webhook firmati.

Il riferimento completo con tutti i campi è nella documentazione API. Documentazione API

Chiavi API

I proprietari e gli amministratori creano le chiavi in Sviluppatori. Una chiave viene mostrata una sola volta: salvala nelle impostazioni segrete della tua app, mai nel codice che gira in un browser. Gli ad creati con una chiave contano nel piano dello workspace, proprio come gli ad creati nell'app.

Authorization: Bearer rl_live_…

Crea un ad

Invia un brief, facoltativamente con un brand, media e formati. La risposta contiene un ID del job; l’ad viene creato in background.

curl https://reelamo.com/v1/jobs \
  -H "Authorization: Bearer $REELAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Sourdough baked fresh every morning. 20% off this weekend.",
    "brand_id": "brd_…",
    "duration": 15,
    "formats": ["9x16", "1x1"],
    "webhook_url": "https://example.com/hooks/reelamo"
  }'

Aggiungi "draft": true per ottenere prima uno storyboard e "variants": 3 per più storyboard con concept diversi. Rendering di una bozza più tardi con POST /v1/jobs/{id}/render.

Stato e download

GET /v1/jobs/{id} restituisce lo stato (in coda, poi i passaggi di elaborazione, poi completato, draft o fallito) e, quando è completato, link di download firmati per formato e una miniatura. I link sono temporanei: richiedi di nuovo il job per ottenere link aggiornati.

Webhook

Con un webhook_url inviamo una POST al tuo indirizzo quando l'ad è pronto, fallito o quando uno storyboard è pronto. L'evento è nell'intestazione X-Reelamo-Event e nel body: job.done, job.failed o job.draft. Il body contiene lo stesso oggetto job dell'endpoint di stato, più un delivery_id univoco.

• L'indirizzo deve essere raggiungibile pubblicamente; gli indirizzi di rete interni e privati vengono rifiutati. Usa https.
• Rispondi con uno stato 2xx entro 15 secondi. Fai il lavoro vero dopo aver risposto.
• Se la consegna non riesce, riproviamo dopo 10 secondi, 1 minuto, 5 minuti e 30 minuti. I reindirizzamenti non vengono seguiti.
• Una consegna può arrivare due volte per errore: usa delivery_id o l'ID del job per ignorare i duplicati.

Verifica delle firme

Ogni webhook è firmato con il segreto webhook del tuo workspace (in Sviluppatori). L'intestazione X-Reelamo-Signature ha un aspetto come t=1760000000,v1=… dove v1 è un HMAC-SHA256 del timestamp, un punto e il corpo grezzo. Verificalo prima di fidarti del contenuto e rifiuta timestamp vecchi:

import hashlib, hmac, time

def verify(body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = int(parts["t"]), parts["v1"]
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig) and abs(time.time() - ts) < tolerance

Limiti e buone pratiche

• Il tuo piano stabilisce quanti ad possono essere creati contemporaneamente e quanto possono durare; le richieste oltre il limite restituiscono un errore con un messaggio chiaro (ad esempio stato 402 quando gli ad mensili sono esauriti, o 429 quando si stanno creando troppi ad contemporaneamente).
• Invia l’header Idempotency-Key con POST /v1/jobs per riprovare una richiesta in sicurezza senza creare un secondo ad.
• Ruota subito una chiave o il segreto del webhook se potrebbe essere stato compromesso.