Siirry sisältöön
Yleiskuva Yleiskuva Uutiset Uutiset
Jaa

Webhookit ja tapahtumat

Reaaliaikaiset tapahtumat. HMAC-varmennettu toimitus.

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

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

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

Käytettävissä olevat tapahtumat

22 tapahtumatyyppiä, ryhmitelty entiteetin mukaan

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

Asiakirjat

14
  • document.uploaded Uusi asiakirja ladattu työtilaan
  • 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 Asiakirja siirretty roskakoriin
  • document.restored Asiakirja palautettu roskakorista
  • document.moved Asiakirja siirretty työtilojen 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

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

Workspaces

2
  • workspace.shared Työtila jaettu käyttäjän tai tiimin kanssa
  • workspace.unshared Työtilan käyttöoikeus peruutettu

Tehtävät

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

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.

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 (oletusarvo 10 000)
  • 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

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

    IP-osoite validoidaan uudelleen lähetettäessä ja lukitaan CURLOPT_RESOLVEn avulla.

  • 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-tapahtumatunnuksen. 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 yritystä kohden (oletusarvo 10.000)
  • 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.

Video

Webhotit toiminnassa

Katsokaa videolta, miten PaperOffice-webhookit toimivat käytännössä.

Webhotit toiminnassa

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, työtilat 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.

Missä haluatte kokeilla PaperOfficea?

Tietokone ja älypuhelin yhdistetty: työtila tietokoneella, kerääminen puhelimella.

Testiversio on valmis

Mistä haluatte aloittaa?

Täysi työtila on optimoitu tietokoneelle. Mobiiliversio soveltuu dokumenttien keräämiseen, tarkistamiseen ja hyväksymiseen.

app.paperoffice.ai

Aloittakaa tietokoneella

Henkilökohtainen kirjautumislinkki lähetetään ilmoitettuun sähköpostiosoitteeseen.

Avatkaa PaperOffice Mobile

Kerätkää ja käsitelkää dokumentteja suoraan älypuhelimella.

Avatkaa mobiiliversio
Rekisteröitykää veloituksetta Avaa sovellus PaperOffice-sovellus Koko tuote: selain, työpöytä ja mobiili. Tallentakaa, järjestäkää, hakekaa ja käsittekää asiakirjoja tiimin kanssa. Ilmainen tili vaaditaan Avaa Playground Playground Kokeilkaa valittuja toimintoja heti — ilman rekisteröitymistä, rajoitetulla demo-API-avaimella. Ei rekisteröitymistä, mutta rajoitettu demo-API-avain