Webhooks

Setup

Buat endpoint webhook — secret dikembalikan sekali. Simpan untuk verifikasi signature.

curl -X POST https://api.platform.kakak.ai/v1/webhook-endpoints \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/webhooks/kakak","events":["run.succeeded","run.failed"]}'

# Response: {"id":"whk_...","secret":"abc123...","warning":"Store this secret now"} 

Verify Signatures

Setiap delivery menyertakan header signature (Stripe-style):

X-Kakak-Event: run.succeeded
X-Kakak-Delivery: whd_...
X-Kakak-Signature: t=1718530000,v1=<hex(HMAC-SHA256(secret, t.body))>

Verifikasi: HMAC-SHA256(secret, "{timestamp}.{rawBody}"). Constant-time compare. Tolak timestamp lebih dari 5 menit (replay protection).

Events

run.succeeded, run.failed, run.canceled, reference_document.ready.

Payload: { "id": "evt_...", "type": "run.succeeded", "data": { "run": {...} } } — full run object dengan output, credits, usage.

Retries

Exponential backoff: 1m, 5m, 30m, 2h, 6h — cap ~24h. Timeout 10 detik per attempt. Harus return 2xx.