İçeriğe atlayın
Genel bakış Genel bakış Haberler Haberler
Paylaş

Webhooks ve Olaylar

Gerçek zamanlı olaylar. HMAC imzalı teslim edildi.

Bir belge, iş, çalışma alanı veya görev değiştiğinde PaperOffice uç noktanızı arar. Hiçbir polling yok.

22 olay türü, HMAC-SHA256 imzası, üç yeniden deneme stratejisi ve her deneme için bir teslimat günlüğü.

Her teslimatta HMAC-SHA256 En fazla 10 tekrar (standart 5) Event-ID ile idempotent

Kullanılabilir Etkinlikler

22 Etkinlik türü, varlık gruplandırılmış

Tekil etkinlikleri abonelik yapın veya tümü için * yer tutucusunu kullanın.

Belgeler

14
  • document.uploaded Yeni belge bir çalışma alanına yüklendi
  • document.created document.uploaded için takma ad (uyumluluk)
  • document.processed OCR/AI-IDP hattı başarıyla tamamlandı
  • document.edited Belge düzenlendi: meta veriler, etiketler veya içerik güncellendi
  • document.deleted Belge çöp kutusuna taşındı
  • document.restored Belge çöp kutusundan geri yüklendi
  • document.moved Belge çalışma alanları arasında taşındı
  • document.version_created Mevcut bir belgenin yeni sürümü
  • document.lifecycle_changed Saklama/Arşivleme durumu değiştirildi
  • document.comment_added Belgeye yorum eklendi
  • document.note_added Dahili not eklendi
  • document.tag_added Belgeye etiket atandı
  • document.legal_hold_placed Yasal tutma etkinleştirildi (değiştirilemez)
  • document.legal_hold_released Yasal tutma kaldırıldı

İşler

3
  • job.completed Asenkron iş başarıyla tamamlandı
  • job.failed Asenkron iş kesin olarak başarısız oldu
  • job.progress İlerleme güncellemesi uzun işlerde

Workspaces

2
  • workspace.shared Çalışma alanı kullanıcı veya ekip ile paylaşıldı
  • workspace.unshared Çalışma alanı erişimi kaldırıldı

Görevler

3
  • task.created Yeni görev oluşturuldu
  • task.completed Görev tamamlandı olarak işaretlendi
  • task.overdue Görev son tarihini aştı

Payload ve Başlık

Her teslimat aynı şemayı takip eder

Tahmin edilebilir JSON gövdesi, sabit HTTP başlıkları, ISO-8601 UTC zaman damgası.

İstek Gövdesi

{
  "event_type": "document.processed",
  "event_id": "a3b7f9c1d4e8b2a6c9f1d4e7b2a5c8f1",
  "timestamp": "2026-04-17T14:23:11Z",
  "subscription_id": 42,
  "data": {
    "pofid": "doc_01HZY8K3M7P2Q9R5T1V6W4X2Y8",
    "workspace_id": 17,
    "filename": "invoice-2026-04-17.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 284521,
    "processing_result": {
      "ocr_done": true,
      "classification": "invoice",
      "confidence": 0.98
    }
  }
}

HTTP İstek Başlığı

Başlık Örnek Değer Anlam
Content-Type application/json Her zaman JSON, UTF-8 kodlu
User-Agent PaperOffice-Webhook/1.0 Güvenlik duvarı izin listeleri için sabit tanımlayıcı
X-PaperOffice-Event document.processed Teslim edilen olay türü
X-PaperOffice-Event-ID a3b7f9c1… 128-bit benzersiz kimlik. İdempotans anahtarı olarak kullanın.
X-PaperOffice-Subscription-ID 42 Etkinliği alan aboneliğin kimliği
X-PaperOffice-Signature sha256=… Ham gövdenin HMAC-SHA256'si, hex kodlu
cURL
curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "My Production Webhook",    "url": "https://yourdomain.com/webhooks/paperoffice",    "events": ["document.processed", "job.completed", "job.failed"],    "retry_policy": "exponential",    "max_retries": 5,    "timeout_ms": 10000  }'

İmza doğrulaması

Her teslimatı HMAC-SHA256 ile doğrulayın

Ortak gizli anahtarınızı kullanarak ham istek gövdesi üzerinde HMAC-SHA256 hesaplayın ve sonucu X-PaperOffice-Signature ile karşılaştırın — sabit süreli olmalıdır.

  • Sabit sürede karşılaştırma

    hash_equals, hmac.compare_digest veya crypto.timingSafeEqual: Karşılaştırma süre farklarını ifşa etmemelidir.

  • Ham Body'yi imzalayın

    İmza, değiştirilmemiş request-body için geçerlidir. Doğrulamadan önce JSON'u ayrıştırmayın, aksi takdirde hash farklılık gösterecektir.

  • API ile abonelik

    name, url ve events ile POST /latest/webhooks/subscribe çağrısı yapın. secret boş bırakılırsa, PaperOffice onu oluşturur ve tek seferlik olarak döndürür.

Yeniden Deneme ve Teslimat

10'a kadar tekrar ile üç yeniden deneme stratejisi

Her abonelik için politika seçin. Her deneme, durum kodu, yanıt gövdesi ve zaman ölçümü ile günlüğe kaydedilir.

  • Varsayılan exponential

    Üstel (Varsayılan)

    Deneyler arasındaki süre her başarısız denemeden sonra iki katına çıkar.

  • linear

    Doğrusal

    Deneyler arasındaki süre sabit bir artışla büyür.

  • none

    Yok

    5xx dahil hiçbir tekrar yok (gönder ve unut). Test hook'ları için kullanışlıdır.

  • Başarı Zaman aşımı penceresi içinde HTTP 2xx
  • Maks. Tekrar Sayısı En fazla 10 tekrar (varsayılan 5)
  • Zaman Aşımı Deneme başına 1.000–30.000 ms (varsayılan 10.000)
  • Teslimat günlüğü Her denetim günlüğe kaydedilir; abonelik silinse bile günlük saklanır.

Yönetim-API

/latest/webhooks/ altında beş uç nokta

Abonelik oluşturma, listeleme, güncelleme ve silme — ayrıca bir test uç noktası. Her çağrı bir Bearer token içerir.

  • POST /webhooks/subscribe Abonelik oluşturun; yükler HMAC-SHA256 ile imzalanır MCP aracıpo-webhooks-subscribe
  • GET /webhooks/list Hesabın tüm webhook aboneliklerini listeleyin MCP aracıpo-webhooks-list
  • POST /webhooks/update URL, olaylar, üstbilgiler, yeniden deneme politikası veya etkin durumu güncelleyin MCP aracıpo-webhooks-update
  • POST /webhooks/delete Aboneliği silin; teslimat günlüğü korunur MCP aracıpo-webhooks-delete
  • POST /webhooks/test Bir aboneliğe test olayı gönderin ve teslimatı doğrulayın MCP aracıpo-webhooks-test

Güvenlik

Temelden güçlendirilmiş

Her teslimatta devreye giren altı mekanizma — PaperOffice tarafında ve sizin tarafınızda.

  • HMAC-SHA256

    Her teslimat, gizli anahtarınızla imzalanır. Karşılaştırma kesinlikle sabit zamanda gerçekleşmelidir.

  • SSRF Koruması

    Abone olurken ve gönderim sırasında özel ve dahili IP'ler, localhost ve bulut meta veri uç noktaları engellenir.

  • DNS Rebinding'e karşı güvenli

    Gönderim sırasında IP yeniden doğrulanır ve CURLOPT_RESOLVE ile sabitlenir.

  • HTTPS önerilir

    http ve https kabul edilir. Üretim ortamı için HTTPS öneriyoruz.

  • Event-ID ile idempotans

    Her teslimat benzersiz bir X-PaperOffice-Event-ID içerir. Tarafınızda deduplikasyon yapın.

  • Tam teslimat günlüğü

    Tüm denemeler günlüğe kaydedilir: Durum kodu, Yanıt Gövdesi, Zaman ölçümü, Hata mesajı.

Limitler

Aboneliğe göre teslim davranışı yapılandırılabilir

Tüm değerleri oluştururken veya daha sonra /webhooks/update üzerinden abonelik başına, hesap başına değil ayarlayın.

  • 0–10 Teslim başına tekrarlar (varsayılan 5)
  • 1.000-30.000 ms Deneme başına zaman aşımı (varsayılan 10.000)
  • 3 Yeniden deneme politikaları: none, linear, exponential
  • HMAC-SHA256 Her teslimde imza

Webhook'lar Professional planından itibaren kullanılabilir. Kurulumunuza uygun planı fiyat listesi gösterir.

Video

Eylem Halindeki Webhook'lar

PaperOffice'un webhook'larının pratikte nasıl çalıştığını videoda izleyin.

Eylem Halindeki Webhook'lar

Sıkça Sorulan Sorular

Webhooklara İlişkin Sıkça Sorulan Sorular

Teslimatı nasıl doğrularım?

Aboneliğinizin gizli anahtarıyla ham request gövdesi üzerinde HMAC-SHA256 hesaplayın ve sonucu sabit süreli bir şekilde X-PaperOffice-Signature başlığındaki değerle (format: sha256=<hex>) karşılaştırın. İmza eşleşmiyorsa HTTP 401 yanıtı verin ve gövdeyi işleme almayın.

Secret nereden geliyor?

Aboneliği POST /latest/webhooks/subscribe üzerinden oluştururken secret alanını boş bırakırsanız, PaperOffice bir secret oluşturur ve bunu yanıtta tek seferlik olarak döndürür. POST /latest/webhooks/update ile bu değeri istediğiniz zaman değiştirebilirsiniz.

Uç noktam yanıt vermezse ne olur?

HTTP 2xx dışında her yanıt veya zaman aşımı bir başarısızlık olarak sayılır. Yeniden deneme politikasına (üstel, doğrusal, yok) bağlı olarak PaperOffice, ayarlanan tekrar sayısı (0-10, varsayılan 5) kadar teslimatı tekrarlar. Her deneme; durum kodu, yanıt ve zaman ölçümü ile birlikte teslimat günlüğünde yer alır.

Aynı teslimat iki kez ulaşabilir mi?

Evet, zaman aşımından sonra yapılan yeniden denemelerde bu mümkündür. Bu nedenle X-PaperOffice-Event-ID üzerinden deduplikasyon yapınız: ID olay başına benzersizdir ve veritabanınızda bir idempotency anahtarı olarak uygundur.

Hangi olaylara abone olabilirim?

Dört gruptan 22 olay türü: Belgeler, İşler, Çalışma Alanları ve Görevler. Tek tek olaylara veya joker karakter * kullanarak hepsine abone olabilirsiniz. Filtreler (örneğin workspace_id veya pofid) ile aboneliği ek olarak daraltabilirsiniz.

Webhook'lar hangi planda dahildir?

Webhook'lar Professional planından itibaren mevcuttur. Kurulumunuza hangi planın uygun olduğunu fiyat listesi gösterir.

PaperOffice’i nerede denemek istersiniz?

Bilgisayar ve akıllı telefon bağlı: Bilgisayarda çalışma alanı, telefonda yakalama.

Deneme sürümünüz hazır

Nerede başlamak istersiniz?

Tam çalışma alanı bilgisayar için optimize edilmiştir. Mobil sürüm belgeleri yakalamak, incelemek ve onaylamak için uygundur.

app.paperoffice.ai

Bilgisayarda başla

Kişisel erişim bağlantısını e-posta adresinize göndereceğiz.

PaperOffice Mobile'ı aç

Belgeleri doğrudan akıllı telefonla yakalayın ve düzenleyin.

Mobil sürümü aç
Ücretsiz kayıt Uygulamayı aç PaperOffice uygulaması Tam ürün: web, masaüstü ve mobil. Belgeleri yakalayın, düzenleyin, arayın ve ekibinizle üzerinde çalışın. Ücretsiz hesap gereklidir Playground’ı aç Playground Seçili işlevleri hemen deneyin — kayıt olmadan, kısıtlı bir demo API anahtarıyla. Kayıt yok, ancak kısıtlı bir demo API anahtarı