Webhook

Bir document tamamlandiginda (ya da basarisiz oldugunda) delivery queue, batch.callback_url adresine (ya da tenant varsayilanina) ayri bir webhook gonderir. Batch bazinda toplu webhook yoktur — her document kendi bildirimini alir.

Imza dogrulama

Her istek X-Signature: sha256=<hex hmac> basligi tasir. Deger, tenant.webhook_secret ile istek govdesinin (ham JSON body, parse edilmeden once) HMAC-SHA256 imzasidir.

Kendi tarafinizda ayni hesaplamayi yapip sabit zamanli karsilastirma yapmalisiniz (timingSafeEqual / hmac.compare_digest) — string esitligi (===) zamanlama saldirilarina acik oldugu icin kullanilmamalidir. Kod ornekleri sag panelde.

Event tipleri

document.completed — result dolu, error: null
document.failed — result: null, error dolu

Retry politikasi

Hedef 2xx disinda bir kod donerse ya da timeout olursa, exponential backoff ile tekrar denenir:

1dk -> 5dk -> 30dk -> 2sa -> exhausted

exhausted durumuna ulasan bir job icin istemci GET /v1/jobs/{id} polling'ine dusmelidir — bu endpoint her zaman guncel durumu doner.

Notlar

MVP'de payload formati sabittir; tenant'a ozel sablon destegi yoktur.
callback_url bos birakilirsa tenant.default_callback_url kullanilir.
Webhook endpoint'inizin idempotent olmasi onerilir; ayni document.id icin birden fazla bildirim gelebilir (retry senaryolarinda).

POST <callback_url> Content-Type: application/json X-Signature: sha256=<hex hmac> { "event": "document.completed", "document": { "id": "d_9c1a...", "batch_id": "b_5f2a...", "external_item_ref": "INV-001", "external_batch_ref": "PO-2026-001", "status": "completed", "page_count": 12, "result": { "markdown_url": "https://markdown-cdn.../signed?exp=...", "json_url": "https://markdown-cdn.../signed?exp=..." }, "error": null }, "timestamp": "2026-07-01T09:02:15Z" }

const crypto = require("node:crypto"); function verifySignature(rawBody, headerValue, secret) { const expected = "sha256=" + crypto .createHmac("sha256", secret) .update(rawBody) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(headerValue) ); }

import hashlib import hmac def verify_signature(raw_body: bytes, header_value: str, secret: str) -> bool: expected = "sha256=" + hmac.new( secret.encode(), raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, header_value)

1. deneme -> basarisiz -> 1 dk sonra tekrar 2. deneme -> basarisiz -> 5 dk sonra tekrar 3. deneme -> basarisiz -> 30 dk sonra tekrar 4. deneme -> basarisiz -> 2 sa sonra tekrar 5. deneme -> basarisiz -> exhausted (polling'e dusun)