Webhook ed eventi

Eventi in tempo reale. Consegna firmata con HMAC.

PaperOffice chiama il suo endpoint non appena un documento, lavoro, workspace o attività cambia. Nessun polling.

22 tipi di evento, firma HMAC-SHA256, tre strategie di retry e un registro delle consegne per ogni tentativo.

Sottoscrivere il primo webhook Avviare la prima chiamata API

HMAC-SHA256 ad ogni consegna Fino a 10 ripetizioni (standard 5) Idempotente per ID evento

Eventi in tempo reale. Consegna firmata con HMAC.

Infrastruttura EU proprietaria I suoi dati rimangono in Europa.
ISO/IEC 27001 certificato Sicurezza certificata.
Oltre 24 anni di esperienza Collaudato. Stabile. Futuro garantito.

Eventi disponibili

22 tipi di eventi, raggruppati per entità

Si iscriva a singoli eventi o utilizzi il segnaposto * per tutti.

Documenti

document.uploaded Nuovo documento caricato in un Workspace
document.created Alias per document.uploaded (compatibilità)
document.processed Pipeline OCR/AI-IDP completata con successo
document.edited Documento modificato: metadati, tag o contenuto aggiornati
document.deleted Documento eliminato; delete_mode indica trash (Cestino in Business e Compliance) oppure instant (Definitivamente nell'archivio standard)
document.restored Documento recuperato dal cestino (Business e Compliance)
document.moved Documento spostato tra Workspaces
document.version_created Nuova versione di un documento esistente
document.lifecycle_changed Stato di conservazione/archiviazione modificato
document.comment_added Commento a un documento creato
document.note_added Nota interna allegata
document.tag_added Tag assegnato a un documento
document.legal_hold_placed Legal Hold attivato (immutabile)
document.legal_hold_released Legal Hold revocato

Lavori

job.completed Lavoro asincrono completato con successo
job.failed Lavoro asincrono fallito definitivamente
job.progress Aggiornamento del progresso per lavori più lunghi

Workspaces

workspace.shared Workspace condiviso con un utente o un team
workspace.unshared Accesso a Workspace revocato

Attività

task.created Nuova attività creata
task.completed Attività contrassegnata come completata
task.overdue Scadenza dell'attività superata

Payload e intestazione

Ogni consegna segue lo stesso schema

Prevedibile corpo JSON, intestazioni HTTP fisse, timestamp ISO-8601 UTC.

Corpo della richiesta

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

Intestazioni della richiesta HTTP

Intestazione Valore di esempio Significato

Content-Type application/json Sempre JSON, codificato UTF-8

User-Agent PaperOffice-Webhook/1.0 Identificatore fisso per le whitelist del firewall

X-PaperOffice-Event document.processed Tipo di evento consegnato

X-PaperOffice-Event-ID a3b7f9c1… ID univoco a 128 bit. Utilizzarlo come chiave di idempotenza.

X-PaperOffice-Subscription-ID 42 ID dell'abbonato che riceve l'evento

X-PaperOffice-Signature sha256=… HMAC-SHA256 del corpo grezzo, codificato in esadecimale

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

Verifica della firma

Verificare ogni consegna con HMAC-SHA256

Calcolare l'HMAC-SHA256 sul corpo della richiesta grezzo con il segreto condiviso e confrontare il risultato con X-PaperOffice-Signature — obbligatorio con tempo di esecuzione costante.

Confronto a tempo di esecuzione costante
hash_equals, hmac.compare_digest o crypto.timingSafeEqual: Il confronto non deve rivelare differenze di tempo di esecuzione.
Firmare il corpo grezzo
La firma si applica al corpo della richiesta non modificato. Analizzare il JSON solo dopo la verifica, altrimenti l'hash divergerà.
Abbonamento tramite API
POST /latest/webhooks/subscribe con name, url ed events. Se secret rimane vuoto, PaperOffice lo genera e lo restituisce una sola volta.

Autenticazione e chiavi Collezione Postman

Retry e consegna

Tre strategie di retry, fino a 10 ripetizioni

Scegliere la policy per abbonamento. Ogni tentativo viene registrato con codice di stato, corpo della risposta e misurazione del tempo.

Predefinito exponential
Esponenziale (predefinito)

L'intervallo tra i tentativi raddoppia dopo ogni fallimento.
linear
Lineare

L'intervallo tra i tentativi aumenta di un passo fisso.
none
Nessuna

Nessun retry, nemmeno in caso di errori 5xx (invia e dimentica). Utile per gli hook di test.

Successo HTTP 2xx entro la finestra di timeout
Max retry Fino a 10 retry (impostazione predefinita: 5)
Timeout 1.000–30.000 ms per tentativo (standard 10.000). Il primo tentativo di consegna è limitato a 2 o 5 secondi a seconda dell'evento; i tentativi successivi utilizzano il valore completo.
Registro di consegna Ogni tentativo viene registrato; il registro rimane disponibile anche dopo l'eliminazione dell'abbonamento.

Gestione-API

Cinque endpoint sotto /latest/webhooks/

Creare, elencare, aggiornare ed eliminare abbonamenti — incluso un endpoint di test. Ogni chiamata richiede un token Bearer.

POST /webhooks/subscribe Creare abbonamento; i payload vengono firmati con HMAC-SHA256 Strumento MCPpo-webhooks-subscribe
GET /webhooks/list Elenca tutti gli abbonamenti webhook dell'account Strumento MCPpo-webhooks-list
POST /webhooks/update Aggiorna URL, eventi, intestazioni, politica di retry o stato attivo Strumento MCPpo-webhooks-update
POST /webhooks/delete Eliminare l'abbonamento; il registro di consegna rimane valido Strumento MCPpo-webhooks-delete
POST /webhooks/test Inviare un evento di test a un abbonamento e verificare la consegna Strumento MCPpo-webhooks-test

Visualizzare il server MCP Collezione Postman

Sicurezza

Progettato per la sicurezza fin dall'inizio

Sei meccanismi che intervengono in ogni consegna — da parte di PaperOffice e dalla sua.

HMAC-SHA256
Ogni consegna viene firmata con il suo segreto. Il confronto deve avvenire obbligatoriamente in tempo costante.
Protezione SSRF
Gli indirizzi IP privati e interni, localhost e gli endpoint dei metadati cloud vengono bloccati durante la sottoscrizione e l'invio.
Sicuro contro il DNS Rebinding
L'indirizzo di destinazione viene verificato nuovamente al momento della consegna.
HTTPS consigliato
Vengono accettati http e https. Per la produzione consigliamo HTTPS.
Idempotenza tramite Event-ID
Ogni consegna include un identificativo evento X-PaperOffice univoco. Effettuare la deduplicazione sul proprio lato.
Registro completo delle consegne
Tutti i tentativi vengono registrati: codice di stato, corpo della risposta, misurazione del tempo, messaggio di errore.

Limiti

Configurazione del comportamento di consegna per abbonamento

Imposti tutti i valori durante la creazione o successivamente tramite /webhooks/update — per abbonamento, non per account.

0–10 Ripetizioni per consegna (impostazione predefinita: 5)
1.000–30.000 ms Timeout per tentativo (standard 10.000, primo tentativo 2–5 s)
3 Politiche di retry: none, linear, exponential
HMAC-SHA256 Firma ad ogni consegna

I webhook sono disponibili a partire dal piano Professional. La panoramica dei prezzi Le mostra quale piano si adatta al suo setup.

Vedere i prezzi Autenticazione e chiavi

Domande

Domande frequenti sui webhook

Come verifico una consegna?

Calcoli l'HMAC-SHA256 sul corpo grezzo della richiesta utilizzando il segreto del suo abbonamento e confronti il risultato in tempo costante con l'intestazione X-PaperOffice-Signature (formato sha256=<hex>). Se la firma non corrisponde, risponda con HTTP 401 e non elabori il corpo.

Da dove proviene il segreto?

Durante la creazione dell'abbonamento tramite POST /latest/webhooks/subscribe. Lasci vuoto il campo secret; PaperOffice genererà un segreto e lo restituirà una sola volta nella risposta. Tramite POST /latest/webhooks/update può sostituirlo in qualsiasi momento.

Cosa succede se il mio endpoint non risponde?

Ogni risposta al di fuori di HTTP 2xx o un timeout conta come tentativo fallito. A seconda della politica di retry (esponenziale, lineare, nessuna), PaperOffice ripete l'erogazione fino al numero impostato di ripetizioni (0–10, predefinito 5). Ogni tentativo è registrato nel log di erogazione con codice di stato, risposta e misurazione del tempo.

La stessa erogazione può arrivare due volte?

Sì, è possibile in caso di ripetizioni dopo un timeout. Effettui quindi la deduplicazione tramite X-PaperOffice-Event-ID: l'ID è unico per ogni evento e si presta come chiave di idempotenza nel suo database.

Quali eventi posso sottoscrivere?

22 tipi di eventi da quattro gruppi: documenti, job, workspace e attività. Può sottoscrivere singoli eventi o tutti con il segnaposto *. Limitate ulteriormente una sottoscrizione tramite filtri (ad esempio workspace_id o pofid).

In quale piano sono inclusi i webhook?

I webhook sono disponibili a partire dal piano Professional. Quale piano si adatta al suo setup è indicato nella panoramica dei prezzi.

Come arrivano le tabelle nel webhook?

Per i campi tabella (ad esempio valori di ispezione o voci di riga), document.processed trasporta anche data.extracted_tables. La sua lista tables contiene una voce per ogni campo tabella con key, label, columns e rows; ogni cella ha value (un numero se PaperOffice ha letto un numero, altrimenti il testo così come stampato) e value_raw (il testo così come stampato, o null se non è noto). extracted_fields rimane invariato. Ogni consegna trasporta al massimo 50 tabelle con fino a 1.000 righe e 40 colonne ciascuna, 2.000 caratteri per cella e 512 KB per tutte le tabelle insieme; se qualcosa viene tagliato, truncated è true e row_count indica il numero totale di righe. La firma copre l'intero corpo della richiesta, incluso extracted_tables.

Cosa è nuovo nell'evento document.processed?

Novità: key_fields ora contiene anche document_number (ad esempio il numero della fattura) e publisher (l'emittente del documento), qualora PaperOffice li abbia letti. Le righe di dettaglio arrivano sotto forma di tabella in data.extracted_tables: la tabella con key __document__content__extraction__line_items (per i campi dell'agente: _line_items) presenta una riga per ciascuna posizione.

Operazioni e fiducia

Cosa i team enterprise verificano prima della prima chiamata

Contratti, sicurezza, supporto e limiti, tutti linkati in un unico luogo.

Prossima fermata

Come procedere

Il prossimo passo consigliato nel funnel degli sviluppatori e due diramazioni pertinenti.

Postman CollectionImporta, testa, debugga in Postman Publishable KeysChiavi sicure nel browser per AI Artifacts e app frontend Primo API callOttenga la chiave, invii la richiesta, verifichi la risposta

Tornare all'ingresso per sviluppatori

Eventi in tempo reale. Consegna firmata con HMAC.

22 tipi di eventi, raggruppati per entità

Ogni consegna segue lo stesso schema

Verificare ogni consegna con HMAC-SHA256

Tre strategie di retry, fino a 10 ripetizioni

Esponenziale (predefinito)

Lineare

Nessuna

Cinque endpoint sotto /latest/webhooks/

Progettato per la sicurezza fin dall'inizio

Configurazione del comportamento di consegna per abbonamento

Domande frequenti sui webhook

Cosa i team enterprise verificano prima della prima chiamata

Come procedere

DMS on-premise per la sua infrastruttura.

IA industriale pronta in Claude e ChatGPT

Non costruire mai da soli.

Document Layer invece di infrastruttura.

Per i partner che sviluppano sulla piattaforma.

Hardware proprio. Datacenter proprio.

31 strumenti gratuiti

PaperOffice PDF Reader