Webhookit ja tapahtumat

Reaaliaikaiset tapahtumat. HMAC-varmennettu toimitus.

Name: Reaaliaikaiset tapahtumat. HMAC-varmennettu toimitus.
Uploaded: 2026-10-07T04:30:47.293Z
Description: Reaaliaikaiset tapahtumat. HMAC-varmennettu toimitus.

PaperOffice kutsuu päätepistesivustoa välittömästi, kun dokumentti, työpöytätyötila, Workspace tai tehtävä muuttuu. Ei pollingia.

22 tapahtumatyyppiä, HMAC-SHA256-varmenne, kolme retry-strategiaa ja yksi toimitusloki per yritys.

Ensimmäisen webhookin tilaus Ensimmäisen API-kutsun aloitus

HMAC-SHA256 jokaisessa toimituksessa Enintään 10 toistoa (vakio 5) Idempotentti tapahtumatunnuksen perusteella

Reaaliaikaiset tapahtumat. HMAC-varmennettu toimitus.

Oma EU-infrastruktuuri Tietonne pysyvät Euroopassa.
ISO/IEC 27001 -sertifioitu Turvallisuus sertifioitu.
24+ vuoden kokemus Testattu. Vakaa. Tulevaisuuden varma.

Käytettävissä olevat tapahtumat

22 tapahtumatyyppiä, ryhmitelty entiteetin mukaan

Tilatkaa yksittäisiä tapahtumia tai käyttäkää jokerimerkkiä * kaikkien osalta.

Asiakirjat

document.uploaded Uusi asiakirja ladattu Workspaceen
document.created Alias document.uploaded-yhteydelle (yhteensopivuus)
document.processed OCR-/AI-IDP-pipeline suoritettu onnistuneesti
document.edited Asiakirjaa muokattu: päivitetyt metatiedot, tunnisteet tai sisältö
document.deleted Dokument poistettu; delete_mode näyttää trash (roskakori Business:ssä ja Compliance:ssä) tai instant (lopullisesti oletusarvoisessa)
document.restored Dokumentti palautettu roskakorista (Business ja Compliance)
document.moved Asiakirja siirretty Workspacejen välillä
document.version_created Olemassa olevan asiakirjan uusi versio
document.lifecycle_changed Säilytys-/arkistointitila muuttunut
document.comment_added Kommentti asiakirjaan luotu
document.note_added Sisäinen huomautus liitetty
document.tag_added Tunniste jaettu asiakirjalle
document.legal_hold_placed Oikeudellinen säilytys aktivoitu (muuttumaton)
document.legal_hold_released Oikeudellinen säilytys poistettu

Työtehtävät

job.completed Asynkroninen tehtävä suoritettu onnistuneesti
job.failed Asynkroninen tehtävä epäonnistui lopullisesti
job.progress Edistymispäivitys pidemmissä tehtävissä

Workspaces

workspace.shared Workspace jaettu käyttäjän tai tiimin kanssa
workspace.unshared Workspacen käyttöoikeus peruutettu

Tehtävät

task.created Uusi tehtävä luotu
task.completed Tehtävä merkitty suoritetuksi
task.overdue Tehtävän määräaika on umpeutunut

Kuormake ja otsikko

Jokainen toimitus noudattaa samaa kaavaa

Ennustettava JSON-runko, kiinteät HTTP-otsikot, ISO-8601-UTC-aikaleima.

Pyyntörunko

{
  "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-pyyntöotsikot

Otsikko Esimerkkiarvo Merkitys

Content-Type application/json Aina JSON, UTF-8-koodattu

User-Agent PaperOffice-Webhook/1.0 Kiinteä tunniste palomuuri-sallituslistoja varten

X-PaperOffice-Event document.processed Toimitettu tapahtumatyyppi

X-PaperOffice-Event-ID a3b7f9c1… 128-bittinen uniikki ID. Käyttäkää tätä idempotenssiavaimena.

X-PaperOffice-Subscription-ID 42 Tilaus, joka vastaanottaa tapahtuman

X-PaperOffice-Signature sha256=… Raw-bodyn HMAC-SHA256, heksakoodattuna

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

Allekirjoituksen vahvistus

Vahvistakaa jokainen toimitus HMAC-SHA256:lla

Laskekaa HMAC-SHA256 raa'asta pyynnön rungosta yhteisellä salaisuudellanne ja verratkaa tulosta X-PaperOffice-Signature-otsikkoon — pakollisesti vakioajassa.

Vertailu vakioajassa
hash_equals, hmac.compare_digest tai crypto.timingSafeEqual: Vertailun ei saa paljastaa ajoeroja.
Allekirjoita raaka request-body
Allekirjoitus koskee muuttumatonta request-bodyä. Jäsentäkää JSON vasta tarkistuksen jälkeen, muuten hash poikkeaa.
Tilaa palvelu API:lla
POST /latest/webhooks/subscribe parametreilla name, url ja events. Jos secret jätetään tyhjäksi, PaperOffice luo sen ja palauttaa sen kerran.

Todennus & avaimet Postman-kokoelma

Retry-toimitus

Kolme retry-strategiaa, jopa 10 toistoa

Valitkaa käytäntö tilauksen mukaan. Jokainen yritys kirjataan statuskoodilla, response-bodyllä ja mittauksella.

Oletus exponential
Eksponentiaalinen (oletus)

Yritysten välinen aika kaksinkertaistuu jokaisen epäonnistuneen yrityksen jälkeen.
linear
Lineaarinen

Yritysten välinen aika kasvaa kiinteällä askeleella.
none
Ei toistoa

Ei toistoa, edes 5xx-virheissä (lähetä ja unohda). Hyödyllinen testikoukuille.

Onnistuminen HTTP 2xx aikarajan sisällä
Maks. toistot Enintään 10 toistoa (oletusarvo 5)
Aikakatkaisu 1 000–30 000 ms per yritys (vakioarvo 10 000). Ensimmäinen toimitusyritys on rajoitettu 2 tai 5 sekuntiin tapahtumasta riippuen; toistot käyttävät koko arvoa.
Toimitusloki Jokainen yritys kirjataan; lokitiedot säilyvät myös tilauksen poistamisen jälkeen.

Hallinto-API

Viisi päätepistettä osoitteessa /latest/webhooks/

Luo, hae, päivitä ja poista tilaukset sekä testaa päätepistettä. Jokainen pyyntö sisältää Bearer-tokenin.

POST /webhooks/subscribe Luo tilaus; payloadit allekirjoitetaan HMAC-SHA256:lla MCP-työkalupo-webhooks-subscribe
GET /webhooks/list Hae kaikki tilin webhook-tilaukset MCP-työkalupo-webhooks-list
POST /webhooks/update Päivitä URL, tapahtumat, otsikot, retry-käytäntö tai aktiivinen tila MCP-työkalupo-webhooks-update
POST /webhooks/delete Tilaa poistaminen; toimituslokki säilyy MCP-työkalupo-webhooks-delete
POST /webhooks/test Lähetä testitapahtuma tilaukselle ja tarkista toimitus MCP-työkalupo-webhooks-test

MCP-palvelin Postman-kokoelma

Turvallisuus

Alusta asti vahvistettu

Kuusi mekanismia, jotka aktivoituvat jokaisen toimituksen yhteydessä — PaperOfficen puolella ja teidän.

HMAC-SHA256
Jokainen toimitus allekirjoitetaan salasanalla. Vertailun on suoritettava vakiotilassa.
SSRF-suojaus
Yksityiset ja sisäiset IP-osoitteet, localhost ja pilvimetadata-päätepisteet estetään tilauksen yhteydessä ja lähetettäessä.
DNS-rebinding-turvallinen
Kohdeosoite tarkistetaan uudelleen toimituksen yhteydessä.
HTTPS suositeltu
Sekä http että https hyväksytään. Tuotantokäyttöön suosittelemme HTTPS:iä.
Idempotenssi tapahtumatunnuksen avulla
Jokainen toimitus sisältää yksilöllisen X-PaperOffice-Event-ID-tunnisteen. Tehkää deduplikaatio omalla puolellanne.
Täysi toimitusloki
Kaikki yritykset lokitetaan: statuskoodi, vastausruumis, aikamittaus, virheilmoitus.

Rajoitukset

Toimituskäyttäytyminen konfiguroitavissa tilauksen mukaan

Asettakaa kaikki arvot luomisen yhteydessä tai myöhemmin /webhooks/update -osoitteen kautta — jokaisen tilauksen perusteella, ei tilin perusteella.

0–10 Toistot toimitusta kohden (oletusarvo 5)
1 000–30 000 ms Aikakatkaisu per yritys (vakioarvo 10 000, ensimmäinen yritys 2–5 s)
3 Retry-poliitikot: none, linear, exponential
HMAC-SHA256 Alle toimituksissa käytettävä allekirjoitus

Webhookit ovat saatavilla vain Professional-suunnitelmalla. Katsokaa hintaohjeesta, mikä suunnitelma sopii asetukseenne.

Hinnat Todennus ja avaimet

Kysymykset

Usein kysytyt kysymykset webhookeista

Miten vahvistan toimituksen?

Laskekaa HMAC-SHA256 raa'asta pyynnön rungosta tilauksenne salaisuudella ja verratkaa tulosta vakioajassa X-PaperOffice-Signature -otsikon arvoon (muoto sha256=<hex>). Jos allekirjoitus ei täsmää, palauttakaa HTTP 401 -vastaus älkääkä käsitelkö runkoa.

Mistä salasanat saadaan?

Tilausta luotaessa POST /latest/webhooks/subscribe -kutsulla. Jättäkää secret-kenttä tyhjäksi, niin PaperOffice luo salaisuuden ja palauttaa sen kerran vastauksessa. Voitte vaihtaa sen milloin tahansa POST /latest/webhooks/update -kutsulla.

Mitä tapahtuu, jos päätepisteeni ei vastaa?

Vastausunto, joka ei ole HTTP 2xx tai aikakatkaisu lasketaan epäonnistuneeksi yritykseksi. PaperOffice toistaa toimituksen retry-käytännön (eksponentiaalinen, lineaarinen, ei mitään) mukaisesti ennalta asetettuun toistojen määrään (0–10, oletus 5) saakka. Jokainen yritys kirjataan toimituslokiin tilakoodin, vastauksen ja mittausajan kanssa.

Voiko sama toimitus saapua kahdesti?

Kyllä, se on mahdollista aikakatkauksen jälkeen tapahtuvien toistojen vuoksi. Deduplikoikaa siis X-PaperOffice-Event-ID:n avulla: ID on uniikki jokaiselle tapahtumalle ja soveltuu idempotenssiavaimeksi tietokannassanne.

Mitä tapahtumia voin tilata?

22 tapahtumatyyppiä neljästä ryhmästä: asiakirjat, työt, Workspacet ja tehtävät. Voitte tilata yksittäisiä tapahtumia tai kaikki paikkamerkillä *. Tilausta voi rajata edelleen suodattimilla (kuten workspace_id tai pofid).

Missä suunnitelmassa webhotit sisältyvät?

Webhookit ovat saatavilla suunnitelmasta Professional alkaen. Hinnasto näyttää, mikä suunnitelma sopii kokoonpanoonne.

Miten taulukot toimitetaan webhookissa?

Taulukkokohtaisille kentille (kuten tarkastusarvoille tai rivikohtaisille tiedoille) document.processed välittää myös data.extracted_tables. Sen lista tables sisältää yhden merkinnän per taulukon kenttä, jossa on key, label, columns ja rows; jokaisessa solussa on arvo value (luku, jos PaperOffice luki luvun, muuten teksti sellaisenaan kuin se on painettu) ja value_raw (teksti sellaisenaan kuin se on painettu tai null, jos sitä ei tunneta). extracted_fields pysyy muuttumattomana. Jokainen toimitus sisältää enintään 50 taulukkoa, joissa on enintään 1 000 riviä ja 40 saraketta kussakin; soluissa on enintään 2 000 merkkiä ja kaikkien taulukoiden yhteiskoko on enintään 512 kt. Jos sisältöä joudutaan rajaamaan, truncated on true ja row_count ilmoittaa rivien kokonaismäärän. Allekirjoitus kattaa koko pyyntörungon, mukaan lukien extracted_tables.

Mitä uutta tapahtumassa document.processed on?

Uutta: key_fields sisältää nyt myös document_number (esimerkiksi laskun numeron) ja publisher (asiakirjan myöntäjän), jos PaperOffice on lukenut ne. Rivit saapuvat taulukkona muodossa data.extracted_tables: taulukossa, jossa on key __document__content__extraction__line_items (agenttikentille: _line_items), on yksi rivi per rivikohta.

Toiminta ja luottamus

Mitä yritystiimit tarkistavat ennen ensimmäistä puhelua

Sopimukset, turvallisuus, tuki ja rajat, kaikki linkitetty yhteen paikkaan.

Seuraava pysäkki

Näin se etenee

Suositeltu seuraava askel kehittäjän suppilossa ja kaksi sopivaa haarautumaa.

Postman CollectionTuo, testaa ja korjaa Postmanissa Publishable KeysSelaimessa turvalliset avaimet AI-artefakteille ja frontend-sovelluksille Ensimmäinen API-kutsuHae avain, lähetä pyyntö, tarkista vastaus

Takaisin kehittäjän aloitukseen

Reaaliaikaiset tapahtumat. HMAC-varmennettu toimitus.

22 tapahtumatyyppiä, ryhmitelty entiteetin mukaan

Jokainen toimitus noudattaa samaa kaavaa

Vahvistakaa jokainen toimitus HMAC-SHA256:lla

Kolme retry-strategiaa, jopa 10 toistoa

Eksponentiaalinen (oletus)

Lineaarinen

Ei toistoa

Viisi päätepistettä osoitteessa /latest/webhooks/

Alusta asti vahvistettu

Toimituskäyttäytyminen konfiguroitavissa tilauksen mukaan

Usein kysytyt kysymykset webhookeista

Mitä yritystiimit tarkistavat ennen ensimmäistä puhelua

Näin se etenee

Paikallinen DMS infrastruktuurillenne.

Toimialojen AI valmiina Claude & ChatGPT:ssa

Älä rakenna yksin.

Dokumenttikerros, ei infrastruktuuri.

Kumppaneille, jotka rakentavat päälle.

Oma laitteisto. Oma Datacenter.

31 ilmaista työkalua

PaperOffice PDF Reader