Helpcentrum / API en webhooks

API en webhooks

Maak ads vanuit je eigen app en krijg een melding wanneer ze klaar zijn, met ondertekende webhooks.

De volledige referentie met elk veld staat in de API-documentatie. API-docs

API-sleutels

Eigenaren en admins maken sleutels aan onder Developers. Een sleutel wordt maar één keer getoond: sla hem op in de geheime instellingen van je app, nooit in code die in een browser draait. Ads die met een sleutel worden gemaakt, tellen mee voor het plan van je workspace, net als ads die in de app worden gemaakt.

Authorization: Bearer rl_live_…

Een ad maken

Stuur een briefing, optioneel met een merk, media en formaten. Het antwoord bevat een job-ID; de ad wordt op de achtergrond gemaakt.

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"
  }'

Voeg "draft": true toe om eerst een storyboard te krijgen, en "variants": 3 voor meerdere storyboards met verschillende concepten. Render later een draft met POST /v1/jobs/{id}/render.

Status en downloads

GET /v1/jobs/{id} geeft de status terug (in wachtrij, daarna verwerkingsstappen, daarna voltooid, draft of mislukt) en, wanneer voltooid, ondertekende downloadlinks per formaat en een thumbnail. Links zijn tijdelijk: vraag de job opnieuw op voor nieuwe links.

Webhooks

Met een webhook_url sturen we een POST naar je adres wanneer de ad klaar is, mislukt of wanneer een storyboard klaarstaat. Het event staat in de X-Reelamo-Event header en de body: job.done, job.failed of job.draft. De body bevat hetzelfde job-object als het status-endpoint, plus een unieke delivery_id.

• Het adres moet publiek bereikbaar zijn; interne en privénetwerkadressen worden geweigerd. Gebruik https.
• Reageer binnen 15 seconden met een 2xx-status. Doe het echte werk nadat je hebt geantwoord.
• Als levering mislukt, proberen we het opnieuw na 10 seconden, 1 minuut, 5 minuten en 30 minuten. Redirects worden niet gevolgd.
• Een levering kan soms twee keer aankomen: gebruik delivery_id of de job-ID om dubbelen te negeren.

Handtekeningen verifiëren

Elke webhook wordt ondertekend met het webhookgeheim van je workspace (onder Developers). De X-Reelamo-Signature-header ziet eruit als t=1760000000,v1=… waarbij v1 een HMAC-SHA256 is van de timestamp, een punt en de ruwe body. Controleer dit voordat je de content vertrouwt, en weiger oude timestamps:

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

Limieten en best practices

• Je plan bepaalt hoeveel ads er tegelijk kunnen worden gemaakt en hoe lang ze mogen zijn; verzoeken boven een limiet geven een foutmelding met een duidelijke melding (bijvoorbeeld status 402 wanneer je maandelijkse ads op zijn, of 429 wanneer er te veel ads tegelijk worden gemaakt).
• Stuur een Idempotency-Key-header mee met POST /v1/jobs om een verzoek veilig opnieuw te proberen zonder een tweede ad te maken.
• Roteer direct een sleutel of het webhookgeheim als het mogelijk is gelekt.