Webhooki i zdarzenia

Zdarzenia w czasie rzeczywistym. Dostarczane z podpisem HMAC.

PaperOffice wywołuje Państwa punkt końcowy, gdy tylko zmieni się dokument, zadanie, obszar roboczy lub zadanie. Bez odpytywania (polling).

22 typy zdarzeń, podpis HMAC-SHA256, trzy strategie ponawiania prób i dziennik dostaw dla każdej próby.

Subskrypcja pierwszego webhooka Pierwsze wywołanie API

HMAC-SHA256 przy każdej dostawie Do 10 powtórzeń (standardowo 5) Idempotentny przez identyfikator zdarzenia

Zdarzenia w czasie rzeczywistym. Dostarczane z podpisem HMAC.

Własna infrastruktura UE Państwa dane pozostają w Europie.
ISO/IEC 27001 certyfikowane Bezpieczeństwo certyfikowane.
Ponad 24 lata doświadczenia Sprawdzone. Stabilne. Bezpieczne dla przyszłości.

Dostępne zdarzenia

22 typy zdarzeń, pogrupowane według encji

Proszę subskrybować pojedyncze zdarzenia lub użyć symbolu wieloznacznego * dla wszystkich.

Dokumenty

document.uploaded Nowy dokument przesłany do Workspace
document.created Alias dla document.uploaded (kompatybilność)
document.processed Pomyślne zakończenie potoku OCR/AI-IDP
document.edited Dokument edytowany: zaktualizowano metadane, tagi lub treść
document.deleted Dokument usunięty; delete_mode wskazuje na trash (kosz w Business i Compliance) lub instant (trwale w standardowym)
document.restored Dokument przywrócony z kosza (Business i Compliance)
document.moved Dokument przeniesiony między Workspace
document.version_created Nowa wersja istniejącego dokumentu
document.lifecycle_changed Zmieniono status przechowywania/archiwizacji
document.comment_added Utworzono komentarz do dokumentu
document.note_added Dołączono notatkę wewnętrzną
document.tag_added Przypisano tag do dokumentu
document.legal_hold_placed Włączono Legal Hold (niezmienność)
document.legal_hold_released Uchycono Legal Hold

Zadania

job.completed Zadanie asynchroniczne pomyślnie zakończone
job.failed Zadanie asynchroniczne ostatecznie nieudane
job.progress Aktualisierung des Fortschritts przy dłuższych zadaniach

Workspaces

workspace.shared Workspace udostępniony użytkownikowi lub zespołowi
workspace.unshared Usunięto dostęp do Workspace

Zadania

task.created Utworzono nowe zadanie
task.completed Oznaczono zadanie jako ukończone
task.overdue Przekroczono termin wykonania zadania

Treść i nagłówek

Każda dostawa stosuje ten sam schemat

Przewidywalny ciało JSON, stałe nagłówki HTTP, znacznik czasu ISO-8601 UTC.

Ciało żądania

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

Nagłówki żądania HTTP

Nagłówek Wartość przykładowa Znaczenie

Content-Type application/json Zawsze JSON, zakodowany w UTF-8

User-Agent PaperOffice-Webhook/1.0 Stały identyfikator dla list dozwolonych zapór ogniowych

X-PaperOffice-Event document.processed Typ dostarczonego zdarzenia

X-PaperOffice-Event-ID a3b7f9c1… 128-bitowy unikalny identyfikator. Proszę użyć go jako klucza idempotentności.

X-PaperOffice-Subscription-ID 42 ID subskrypcji odbierającej zdarzenie

X-PaperOffice-Signature sha256=… HMAC-SHA256 surowego ciała żądania, zakodowane w formacie hex

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';

Weryfikacja sygnatury

Proszę weryfikować każdą dostawę za pomocą HMAC-SHA256

Proszę obliczyć HMAC-SHA256 na podstawie surowego ciała żądania przy użyciu wspólnego klucza tajnego i porównać wynik z nagłówkiem X-PaperOffice-Signature — obowiązkowo z użyciem stałego czasu wykonania.

Porównanie o stałym czasie wykonania
hash_equals, hmac.compare_digest lub crypto.timingSafeEqual: Porównanie nie może ujawniać różnic w czasie wykonania.
Podpisanie ciała żądania
Podpis dotyczy niezmienionego ciała żądania. Proszę parsować JSON dopiero po weryfikacji, w przeciwnym razie hash będzie się różnił.
Subskrypcja przez API
POST /latest/webhooks/subscribe z name, url i events. Jeśli secret pozostanie pusty, PaperOffice wygeneruje go i zwróci jednorazowo.

Uwierzytelnianie i klucze Kolekcja Postman

Ponawianie i dostawa

Trzy strategie ponawiania, do 10 powtórzeń

Proszę wybrać politykę dla każdej subskrypcji. Każda próba jest logowana z kodem statusu, ciałem odpowiedzi i pomiarem czasu.

Domyślne exponential
Eksponencjalne (domyślne)

Odstęp między próbami podwaja się po każdej nieudanej próbie.
linear
Liniowy

Odstęp między próbami rośnie o stały krok.
none
Brak

Brak ponownych prób, nawet w przypadku błędów 5xx (wyślij i zapomnij). Przydatne dla hooków testowych.

Sukces HTTP 2xx w oknie limitu czasu
Maks. liczba ponownych prób Do 10 ponownych prób (domyślnie 5)
Limit czasu 1.000–30.000 ms na próbę (standardowo 10.000). Pierwsza próba dostarczenia jest ograniczona do 2 lub 5 sekund w zależności od zdarzenia, kolejne powtórzenia wykorzystują pełną wartość.
Dziennik dostarczania Każda próba jest logowana; dziennik pozostaje dostępny nawet po usunięciu subskrypcji.

Zarządzanie-API

Pięć punktów końcowych pod /latest/webhooks/

Tworzenie, wyświetlanie, aktualizowanie i usuwanie subskrypcji — w tym punkt końcowy testowy. Każde wywołanie wymaga tokena Bearer.

POST /webhooks/subscribe Utwórz subskrypcję; ładunki są podpisywane za pomocą HMAC-SHA256 Narzędzie MCPpo-webhooks-subscribe
GET /webhooks/list Wyświetl wszystkie subskrypcje webhooków konta Narzędzie MCPpo-webhooks-list
POST /webhooks/update Zaktualizuj URL, zdarzenia, nagłówki, politykę ponawiania lub status aktywności Narzędzie MCPpo-webhooks-update
POST /webhooks/delete Usuń subskrypcję; protokół dostarczania pozostaje nienaruszony Narzędzie MCPpo-webhooks-delete
POST /webhooks/test Wyślij zdarzenie testowe do subskrypcji i sprawdź dostarczenie Narzędzie MCPpo-webhooks-test

Przegląd serwera MCP Kolekcja Postman

Bezpieczeństwo

Wzmocnione od podstaw

Sześć mechanizmów działających przy każdym dostarczeniu — po stronie PaperOffice i po Państwa stronie.

HMAC-SHA256
Każde dostarczenie jest podpisywane Państwa sekretem. Porównanie musi odbywać się w stałym czasie.
Ochrona przed SSRF
Adresy IP prywatne i wewnętrzne, localhost oraz punkty końcowe metadanych chmurowych są blokowane podczas subskrypcji i wysyłania.
Bezpieczny przed DNS rebindingiem
Adres docelowy jest ponownie weryfikowany w momencie dostawy.
Zalecane HTTPS
Akceptowane są protokoły http i https. W przypadku środowiska produkcyjnego zalecamy użycie HTTPS.
Idempotentność dzięki identyfikatorowi zdarzenia
Każda dostawa zawiera unikalny identyfikator X-PaperOffice-Event-ID. Prosimy o deduplikację po swojej stronie.
Pełny protokół dostaw
Wszystkie próby są logowane: kod statusu, ciało odpowiedzi, pomiar czasu, komunikat o błędzie.

Limity

Konfiguracja zachowania dostaw dla każdej subskrypcji

Wszystkie wartości ustawiają Państwo podczas tworzenia lub później za pomocą /webhooks/update — w zależności od subskrypcji, a nie konta.

0–10 Powtórzenia na dostawę (domyślnie 5)
1,0–30,0 s Limit czasu na próbę (standardowo 10.000, pierwsza próba 2–5 s)
3 Polityki ponawiania: none, linear, exponential
HMAC-SHA256 Podpis przy każdej dostawie

Webhooks są dostępne od planu Professional. Który plan pasuje do Państwa konfiguracji, pokaże przegląd cenowy.

Cennik Uwierzytelnianie i klucze

Pytania

Najczęściej zadawane pytania dotyczące webhooków

Jak zweryfikować dostarczenie?

Proszę obliczyć HMAC-SHA256 na surowym ciele żądania przy użyciu sekretu swojej subskrypcji i porównać wynik w stałym czasie z nagłówkiem X-PaperOffice-Signature (format sha256=<hex>). Jeśli sygnatura nie jest poprawna, proszę odpowiedzieć kodem HTTP 401 i nie przetwarzać ciała.

Skąd wziąć sekret?

Podczas tworzenia subskrypcji przez POST /latest/webhooks/subscribe. Jeśli pozostawią Państwo pole secret puste, PaperOffice wygeneruje sekret i zwróci go jednorazowo w odpowiedzi. Mogą Państwo go zastąpić w dowolnym momencie za pomocą POST /latest/webhooks/update.

Co się stanie, jeśli mój endpoint nie odpowie?

Każda odpowiedź spoza zakresu HTTP 2xx lub timeout jest liczona jako nieudana próba. W zależności od polityki ponownych prób (exponential, linear, none) PaperOffice powtarza dostarczanie do ustalonej liczby powtórzeń (0–10, domyślnie 5). Każda próba jest rejestrowana w dzienniku dostarczania wraz ze statusem HTTP, treścią odpowiedzi i czasem trwania.

Czy ta sama wiadomość może zostać dostarczona dwukrotnie?

Tak, jest to możliwe przy ponownych próbach po wystąpieniu timeoutu. Dlatego należy stosować deduplikację za pomocą nagłówka X-PaperOffice-Event-ID: identyfikator ten jest unikalny dla każdego zdarzenia i może służyć jako klucz idempotentny w bazie danych.

Jakie zdarzenia mogę subskrybować?

22 typy zdarzeń z czterech grup: dokumenty, zadania (jobs), workspace'y i aktywności. Można subskrybować pojedyncze zdarzenia lub wszystkie za pomocą symbolu wieloznacznego *. Subskrypcję można dodatkowo zawęzić za pomocą filtrów (np. workspace_id lub pofid).

W której cenniku dostępne są webhooks?

Webhooks są dostępne w planie Professional. Który plan najlepiej odpowiada Państwa potrzebom, pokaże przegląd cenowy.

Jak tabele trafiają do webhooka?

Dla pól tabelarycznych (na przykład wartości kontroli lub pozycji), document.processed przekazuje również data.extracted_tables. Jego lista tables zawiera jeden wpis na każde pole tabelaryczne z key, label, columns i rows; każda komórka posiada value (liczbę, jeśli PaperOffice odczytało liczbę, w przeciwnym razie tekst zgodnie z wydrukiem) oraz value_raw (tekst zgodnie z wydrukiem lub null, jeśli nie jest znany). extracted_fields pozostaje bez zmian. Każda dostawa zawiera co najwyżej 50 tabel po maksymalnie 1 000 wierszy i 40 kolumn każda, do 2 000 znaków na komórkę oraz do 512 KB dla wszystkich tabel razem; jeśli coś zostanie ucięte, truncated przyjmuje wartość true, a row_count podaje pełną liczbę wierszy. Sygnatura obejmuje całe ciało żądania, w tym extracted_tables.

Co nowego w zdarzeniu document.processed?

Nowość: key_fields zawiera również document_number (na przykład numer faktury) oraz publisher (wystawcę dokumentu), jeśli PaperOffice je odczytał. Pozycje dokumentu trafiają w formie tabeli w data.extracted_tables: tabela z key __document__content__extraction__line_items (dla pól agenta: _line_items) zawiera jeden wiersz na każdą pozycję.