Lompat ke konten utama
Ikhtisar Ikhtisar Berita Berita
Bagikan

Webhooks & Acara

Acara Waktu Nyata. Ditandatangani HMAC.

PaperOffice memanggil endpoint Anda segera setelah dokumen, pekerjaan, workspace, atau tugas berubah. Tidak ada polling.

22 jenis acara, tanda tangan HMAC-SHA256, tiga strategi retry, dan log pengiriman per percobaan.

HMAC-SHA256 pada setiap pengiriman Hingga 10 pengulangan (standar 5) Idempoten berdasarkan Event-ID

Event yang Tersedia

22 Jenis Event, dikelompokkan berdasarkan entitas

Berlangganan event individual atau gunakan placeholder * untuk semua.

Dokumen

14
  • document.uploaded Dokumen baru diunggah ke workspace
  • document.created Alias untuk document.uploaded (kompatibilitas)
  • document.processed Pipeline OCR/AI-IDP berhasil diselesaikan
  • document.edited Dokumen diedit: metadata, tag, atau konten diperbarui
  • document.deleted Dokumen dipindahkan ke tempat sampah
  • document.restored Dokumen dipulihkan dari tempat sampah
  • document.moved Dokumen dipindahkan antar workspace
  • document.version_created Versie baru dari dokumen yang ada
  • document.lifecycle_changed Status penyimpanan/pengarsipan diubah
  • document.comment_added Komentar pada dokumen dibuat
  • document.note_added Catatan internal dilampirkan
  • document.tag_added Tag ditetapkan ke dokumen
  • document.legal_hold_placed Legal Hold diaktifkan (tidak dapat diubah)
  • document.legal_hold_released Legal Hold dibatalkan

Job

3
  • job.completed Job asinkron berhasil diselesaikan
  • job.failed Job asinkron gagal secara permanen
  • job.progress Pembaruan kemajuan untuk pekerjaan berdurasi panjang

Workspaces

2
  • workspace.shared Ruang kerja dibagikan dengan pengguna atau tim
  • workspace.unshared Akses ruang kerja dicabut

Tugas

3
  • task.created Tugas baru dibuat
  • task.completed Tugas ditandai sebagai selesai
  • task.overdue Tugas telah melewati batas waktu

Payload dan Header

Setiap pengiriman mengikuti skema yang sama

Body JSON yang dapat diprediksi, header HTTP tetap, stempel waktu ISO-8601-UTC.

Body Permintaan

{
  "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
    }
  }
}

Header Permintaan HTTP

Header Nilai Contoh Arti
Content-Type application/json Selalu JSON, terkode UTF-8
User-Agent PaperOffice-Webhook/1.0 Identifier tetap untuk daftar izin firewall
X-PaperOffice-Event document.processed Tipe event yang dikirimkan
X-PaperOffice-Event-ID a3b7f9c1… ID unik 128-bit. Gunakan sebagai kunci idempotensi.
X-PaperOffice-Subscription-ID 42 ID dari langganan yang menerima event
X-PaperOffice-Signature sha256=… HMAC-SHA256 dari body mentah, dikodekan dalam heksadesimal
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  }'

Verifikasi tanda tangan

Verifikasi setiap pengiriman dengan HMAC-SHA256

Hitung HMAC-SHA256 pada body permintaan mentah menggunakan rahasia bersama Anda dan bandingkan hasilnya dengan X-PaperOffice-Signature — wajib menggunakan waktu konstan.

  • Perbandingan dengan waktu konstan

    hash_equals, hmac.compare_digest, atau crypto.timingSafeEqual: Perbandingan tidak boleh membocorkan perbedaan waktu.

  • Tandatangani Body Rohen

    Tanda tangan berlaku untuk Body Request yang tidak berubah. Parse JSON hanya setelah pemeriksaan, jika tidak hash akan menyimpang.

  • Berlangganan melalui API

    POST /latest/webhooks/subscribe dengan name, url dan events. Biarkan secret kosong, PaperOffice akan membuatnya dan mengembalikannya sekali.

Retry dan Pengiriman

Tiga Strategi Retry, hingga 10 pengulangan

Pilih kebijakan per langganan. Setiap upaya dicatat dengan status code, Response Body dan pengukuran waktu.

  • Standar exponential

    Eksponensial (Standar)

    Jeda antar percobaan berlipat ganda setelah setiap kegagalan.

  • linear

    Linier

    Jeda antar percobaan bertambah dengan langkah tetap.

  • none

    Tidak ada

    Tidak ada pengulangan, bahkan untuk 5xx (kirim dan lupakan). Berguna untuk hook pengujian.

  • Keberhasilan HTTP 2xx dalam jendela timeout
  • Maks. Pengulangan Hingga 10 pengulangan (standar 5)
  • Batas waktu 1.000–30.000 ms per percobaan (standar 10.000)
  • Log pengiriman Setiap percobaan dicatat; log tetap tersimpan bahkan setelah langganan dihapus.

Manajemen-API

Lima titik akhir di bawah /latest/webhooks/

Buat, daftar, perbarui, dan hapus langganan — termasuk satu titik akhir pengujian. Setiap panggilan menggunakan token Bearer.

  • POST /webhooks/subscribe Buat langganan; payload ditandatangani dengan HMAC-SHA256 Alat MCPpo-webhooks-subscribe
  • GET /webhooks/list Daftar semua langganan webhook akun Alat MCPpo-webhooks-list
  • POST /webhooks/update Perbarui URL, peristiwa, header, kebijakan retry, atau status aktif Alat MCPpo-webhooks-update
  • POST /webhooks/delete Berlangganan dihapus; protokol pengiriman tetap tersimpan Alat MCPpo-webhooks-delete
  • POST /webhooks/test Kirim event uji ke langganan dan periksa pengirimannya Alat MCPpo-webhooks-test

Keamanan

Dibangun dengan pertahanan kuat dari dasar

Enam mekanisme yang aktif pada setiap pengiriman — di sisi PaperOffice dan di sisi Anda.

  • HMAC-SHA256

    Setiap pengiriman ditandatangani dengan Secret Anda. Perbandingan harus dilakukan dalam waktu konstan.

  • Perlindungan SSRF

    IP privat dan internal, localhost, serta endpoint metadata cloud diblokir saat berlangganan dan dispatch.

  • Aman dari DNS Rebinding

    IP divalidasi ulang saat dispatch dan dipin menggunakan CURLOPT_RESOLVE.

  • HTTPS direkomendasikan

    http dan https diterima. Untuk produksi, kami merekomendasikan HTTPS.

  • Idempotensi melalui Event-ID

    Setiap pengiriman menyertakan X-PaperOffice-Event-ID yang unik. Lakukan deduplikasi di sisi Anda.

  • Log pengiriman lengkap

    Semua upaya dicatat: kode status, body respons, pengukuran waktu, pesan error.

Batas

Perilaku pengiriman dapat dikonfigurasi per langganan

Semua nilai ditetapkan saat pembuatan atau kemudian melalui /webhooks/update — per langganan, bukan per akun.

  • 0–10 Pengulangan per pengiriman (standar 5)
  • 1,000–30,000 ms Timeout per percobaan (standar 10.000)
  • 3 Kebijakan retry: none, linear, eksponensial
  • HMAC-SHA256 Tanda tangan pada setiap pengiriman

Webhooks tersedia mulai dari paket Professional. Paket mana yang sesuai dengan pengaturan Anda dapat dilihat dalam ringkasan harga.

Video

Webhook dalam Aksi

Lihat bagaimana PaperOffice Webhook berfungsi dalam praktik — dalam video.

Webhook dalam Aksi

Pertanyaan

Pertanyaan Umum tentang Webhooks

Bagaimana cara memverifikasi pengiriman?

Hitung HMAC-SHA256 pada body permintaan mentah menggunakan rahasia langganan Anda, dan bandingkan hasilnya secara konstan waktu dengan header X-PaperOffice-Signature (format sha256=<hex>). Jika tanda tangan tidak cocok, balas dengan HTTP 401 dan jangan proses body tersebut.

Dari mana asal rahasianya?

Saat membuat langganan melalui POST /latest/webhooks/subscribe. Biarkan bidang rahasia kosong, PaperOffice akan menghasilkan rahasia dan mengembalikannya sekali saja dalam respons. Anda dapat menggantinya kapan saja melalui POST /latest/webhooks/update.

Apa yang terjadi jika endpoint saya tidak merespons?

Setiap respons di luar HTTP 2xx atau timeout dihitung sebagai kegagalan. Tergantung pada kebijakan retry (eksponensial, linear, none), PaperOffice akan mengulang pengiriman hingga jumlah pengulangan yang ditetapkan (0–10, default 5). Setiap upaya dicatat dalam log pengiriman bersama kode status, respons, dan pengukuran waktu.

Apakah pengiriman yang sama dapat diterima dua kali?

Ya, hal ini mungkin terjadi saat retry setelah timeout. Oleh karena itu, lakukan deduplikasi melalui X-PaperOffice-Event-ID: ID tersebut unik per event dan cocok sebagai kunci idempotensi di database Anda.

Event apa saja yang dapat saya langganan?

22 jenis event dari empat grup: Dokumen, Jobs, Workspace, dan Tugas. Anda dapat berlangganan event individual atau semua dengan menggunakan placeholder *. Selain itu, Anda dapat membatasi langganan menggunakan filter (misalnya workspace_id atau pofid).

Dalam paket mana Webhook disertakan?

Webhook tersedia mulai dari paket Professional. Paket yang sesuai dengan setup Anda dapat dilihat pada ringkasan harga.

Di mana Anda ingin menguji PaperOffice?

Komputer dan smartphone terhubung: Workspace di komputer, penangkapan di telepon.

Versi uji coba Anda siap

Di mana Anda ingin memulai?

Workspace lengkap dioptimalkan untuk komputer. Versi mobile cocok untuk menangkap, memeriksa, dan menyetujui dokumen.

app.paperoffice.ai

Mulai di komputer

Kami akan mengirimkan tautan akses pribadi Anda ke alamat email Anda.

Buka PaperOffice Mobile

Tangkap dan edit dokumen langsung dengan smartphone.

Buka versi mobile
Pendaftaran gratis Buka aplikasi Aplikasi PaperOffice Produk lengkap: web, desktop, dan seluler. Tangkap, atur, cari, dan kerjakan dokumen bersama tim. Akun gratis diperlukan Buka Playground Playground Uji fungsi terpilih segera — tanpa pendaftaran, dengan kunci API demo terbatas. Tanpa registrasi, tetapi dengan kunci API demo terbatas