Vada al contenuto principale
Panoramica Panoramica Notizie Notizie
Condividi

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.

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

Eventi disponibili

22 tipi di eventi, raggruppati per entità

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

Documenti

14
  • document.uploaded Nuovo documento caricato in uno spazio di lavoro
  • 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 spostato nel cestino
  • document.restored Documento ripristinato dal cestino
  • document.moved Documento spostato tra spazi di lavoro
  • 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

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

Workspaces

2
  • workspace.shared Area di lavoro condivisa con utente o team
  • workspace.unshared Accesso all'area di lavoro revocato

Attività

3
  • 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
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  }'

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.

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 (impostazione predefinita 10.000)
  • 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

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'IP viene nuovamente validato durante l'invio e fissato tramite CURLOPT_RESOLVE.

  • 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,00–30,0 ms Timeout per tentativo (impostazione predefinita: 10.000)
  • 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.

Video

Webhook in azione

Guardi come funzionano i webhook di PaperOffice nella pratica — nel video.

Webhook in azione

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.

Dove desidera provare PaperOffice?

Computer e smartphone sono collegati: area di lavoro sul computer, acquisizione sul telefono.

La versione di prova è pronta

Da dove si desidera iniziare?

L'area di lavoro completa è ottimizzata per il computer. La versione mobile è ideale per acquisire, verificare e approvare documenti.

app.paperoffice.ai

Iniziare sul computer

Il link di accesso personale verrà inviato all'indirizzo e-mail indicato.

Registrarsi gratuitamente Aprire l’app App PaperOffice Il prodotto completo: web, desktop e mobile. Acquisisca, organizzi, cerchi e lavori sui documenti con il team. È necessario un account gratuito Aprire Playground Playground Provi funzioni selezionate subito — con una chiave API demo limitata. Una chiave API demo con limitazioni