Webhook

GET /v1/jobs/{id} polling'inin push tabanli alternatifidir: surekli durum sormak yerine, bir document completed ya da failed oldugunda backend sizin belirledigin URL'e imzali bir HTTP POST istegi atar. Polling her zaman calisir durumda kalir (webhook basarisiz olsa dahi guvenilir fallback'tir, bkz. Polling); webhook yalnizca gecikmeyi ve gereksiz sorgu trafigini azaltir.

Batch bazinda toplu webhook yoktur — batch icindeki her document kendi bildirimini ayri ayri alir.

Callback URL nasil ayarlanir

Webhook hedefi kalici bir dashboard ayari degil, istek bazinda belirlenir:

• POST /v1/documents ya da POST /v1/batches govdesinde opsiyonel callback_url alani ile gonderilir (bkz. Upload). Ayni tenant'in farkli yuklemeleri farkli URL'lere gidebilir.
• Istekte callback_url bos birakilirsa tenant'in varsayilani (default_callback_url) kullanilir.
• Bu varsayilan ve HMAC imza sirri (webhook_secret) su an self-servis bir panelden ayarlanamiyor — DocsFra operasyon ekibi tarafindan tenant kaydi uzerinde tanimlanir; entegrasyona baslarken bunlari bizimle paylasmaniz gerekir.
• Ikisi de bos ise webhook hic gonderilmez (no-op) — bu durumda istemci yalnizca polling'e guvenmelidir.

Event tipleri ve payload semasi

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

Payload alanlari GET /v1/jobs/{id} ile ayni kaynaktan turetilir:

• id, batch_id, external_item_ref, external_batch_ref
• status, page_count
• partial — true ise en az bir sayfa tum motorlarda islenemedi ama document yine completed sayilir (kismi sonuc, bkz. Polling).
• result.markdown_url, result.json_url — yalnizca completed iken dolu. Sureli signed link'lerdir, webhook gonderilirken bir kez uretilip payload'a gomulur; retry denemelerinde ayni URL tekrar kullanilir (her denemede yeniden imzalanmaz), bu yuzden gecikmis bir teslimat aliyorsaniz linkin suresi dolmus olabilir — bu durumda GET /v1/jobs/{id} ile taze bir link alin.
• error — yalnizca failed iken dolu.

Ornek payload ve tam sema sag panelde.

Imza dogrulama

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

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

Yanit beklentisi

• Endpoint'iniz 10 saniye icinde yanit vermelidir; asilirsa timeout sayilir ve retry sirasina girer.
• Yalnizca HTTP durum kodu kontrol edilir: 2xx (200-299) basarili sayilir, govde icerigi onemli degildir. Bunun disindaki her kod (4xx/5xx dahil) ve baglanti hatasi basarisiz sayilir.

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.

Idempotency

Webhook endpoint'inizin idempotent olmasi gerekir; ayni document.id icin birden fazla bildirim gelebilir (retry senaryolarinda, ya da nadiren ayni denemenin tekrar kuyruklanmasinda). Tekrarlanan istekleri guvenle yok sayabilmek icin document.id + status kombinasyonuna gore kontrol uygulayin.

Notlar

• MVP'de payload formati sabittir; tenant'a ozel sablon destegi yoktur.
• callback_url istekte bos birakilirsa tenant.default_callback_url kullanilir; o da yoksa webhook hic gonderilmez.