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üğü.

İlk webhook'a abone olun İlk API çağrısını başlatma

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

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

Kendi AB Altyapısı Verileriniz Avrupa'da kalır.
ISO/IEC 27001 sertifikalı Güvenlik sertifikalı.
24+ yıl deneyim Kanıtlı. Sağlam. Geleceğe yönelik.

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

document.uploaded Workspace'e yeni belge 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 silindi; delete_mode, trash (Business ve Compliance'deki çöp kutusu) veya instant (standartta kalıcı olarak) gösterir
document.restored Belge çöp kutusundan geri yüklendi (Business ve Compliance)
document.moved Belge Workspaces 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

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

workspace.shared Workspace bir kullanıcıya veya ekibe paylaşıldı
workspace.unshared Workspace erişimi iptal edildi

Görevler

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

1curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \2  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "My Production Webhook",6    "url": "https://yourdomain.com/webhooks/paperoffice",7    "events": ["document.processed", "job.completed", "job.failed"],8    "retry_policy": "exponential",9    "max_retries": 5,10    "timeout_ms": 1000011  }'

1import crypto from 'crypto';2import express from 'express';34const app = express();5const WEBHOOK_SECRET = process.env.PAPEROFFICE_WEBHOOK_SECRET;67app.post('/webhooks/paperoffice', express.raw({ type: 'application/json' }), (req, res) => {8  const signature = req.header('X-PaperOffice-Signature'); // "sha256=..."9  const eventId   = req.header('X-PaperOffice-Event-ID');10  const eventType = req.header('X-PaperOffice-Event');1112  const expected = 'sha256=' + crypto13    .createHmac('sha256', WEBHOOK_SECRET)14    .update(req.body)15    .digest('hex');1617  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {18    return res.status(401).send('invalid signature');19  }2021  const event = JSON.parse(req.body.toString());22  // store eventId as idempotency key -> never process the same ID twice23  console.log(eventType, event.data);24  res.status(200).send('ok');25});

1import hmac, hashlib, os2from flask import Flask, request, abort34app = Flask(__name__)5WEBHOOK_SECRET = os.environ["PAPEROFFICE_WEBHOOK_SECRET"]67@app.route("/webhooks/paperoffice", methods=["POST"])8def paperoffice_webhook():9    signature  = request.headers.get("X-PaperOffice-Signature", "")10    event_id   = request.headers.get("X-PaperOffice-Event-ID", "")11    event_type = request.headers.get("X-PaperOffice-Event", "")1213    expected = "sha256=" + hmac.new(14        WEBHOOK_SECRET.encode(),15        request.get_data(),16        hashlib.sha256,17    ).hexdigest()1819    if not hmac.compare_digest(signature, expected):20        abort(401)2122    payload = request.get_json()23    # store event_id as idempotency key in your DB24    print(event_type, payload["data"])25    return "ok", 200

1<?php2// PaperOffice webhook receiver with HMAC-SHA256 signature verification3$secret = getenv('PAPEROFFICE_WEBHOOK_SECRET');4$raw    = file_get_contents('php://input');56$signature  = $_SERVER['HTTP_X_PAPEROFFICE_SIGNATURE'] ?? '';7$event_id   = $_SERVER['HTTP_X_PAPEROFFICE_EVENT_ID'] ?? '';8$event_type = $_SERVER['HTTP_X_PAPEROFFICE_EVENT'] ?? '';910$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);11if (!hash_equals($expected, $signature)) {12    http_response_code(401);13    exit('invalid signature');14}1516$event = json_decode($raw, true);17// store event_id as idempotency key in your DB18error_log("{$event_type}: " . json_encode($event['data']));19http_response_code(200);20echo 'ok';

İ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.

Kimlik Doğrulama & Anahtarlar Postman Koleksiyonu

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). İlk teslim denemesi, olaya bağlı olarak 2 veya 5 saniye ile sınırlıdır; tekrar denemeler ise tam süreyi kullanır.
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

MCP Sunucusuna Bakın Postman Koleksiyonu

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
Hedef adres, teslimat sırasında tekrar kontrol edilir.
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, ilk deneme 2–5 sn)
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.

Fiyatlar Kimlik Doğrulama & Anahtarlar

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.

Tablolar webhook'a nasıl ulaşır?

Tablo alanları (örneğin muayene değerleri veya kalemler) için document.processed, data.extracted_tables de taşır. Listesi tables, her biri key, label, columns ve rows içeren, tablo alanı başına bir girdi içerir; her hücrede value (PaperOffice bir sayı olarak okuduysa sayı, aksi takdirde yazdırıldığı gibi metin) ve value_raw (yazdırıldığı gibi metin veya bilinmiyorsa null) bulunur. extracted_fields değişmeden kalır. Her teslimatta en fazla 50 tablo, her biri en fazla 1.000 satır ve 40 sütun olmak üzere, hücre başına 2.000 karakter ve tüm tablolar için birlikte 512 KB taşır; herhangi bir kesme olursa truncated, true olur ve row_count toplam satır sayısını belirtir. İmza, extracted_tables dahil olmak üzere istek gövdesinin tamamını kapsar.

document.processed olayında neler yenidir?

Yeni: key_fields artık document_number (örneğin fatura numarası) ve publisher (belgenin düzenleyeni) bilgilerini de taşır; bunlar PaperOffice tarafından okunmuşsa geçerlidir. Satır detayları, data.extracted_tables içinde bir tablo olarak iletilir: key __document__content__extraction__line_items tablosu (ajan alanları için: _line_items) her satır detayı için bir satır içerir.

Operasyon ve güven

Kurumsal ekiplerin ilk çağrıdan önce neyi kontrol ettiği

Sözleşmeler, güvenlik, destek ve limitler, her şey tek bir yerde bağlantılı.

Sonraki durak

Devamı şöyle

Developer hunisindeki önerilen bir sonraki adım ve iki uygun yan dal.

Postman CollectionPostman'da içe aktarma, test etme ve hata ayıklama Publishable KeysAI Artefaktları ve ön uç uygulamalar için tarayıcı güvenli anahtarlar İlk API ÇağrısıAnahtarı alın, isteği gönderin, yanıtı kontrol edin

Developer girişine dönüş

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

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

Her teslimat aynı şemayı takip eder

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

10'a kadar tekrar ile üç yeniden deneme stratejisi

Üstel (Varsayılan)

Doğrusal

Yok

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

Temelden güçlendirilmiş

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

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

Kurumsal ekiplerin ilk çağrıdan önce neyi kontrol ettiği

Devamı şöyle

Altyapınız için yerel DMS.

Claude ve ChatGPT ile hazır sektör yapay zekası

Asla tek başına geliştirme yapma.

Altyapı yerine Document Layer.

PaperOffice üzerine inşa eden partnerler için.

Kendi donanım. Kendi Datacenter.

31 ücretsiz araç

PaperOffice PDF Reader