Уебхукове и събития

Събития в реално време. Доставени с HMAC подпис.

Name: Събития в реално време. Доставени с HMAC подпис.
Uploaded: 2026-10-07T04:30:47.293Z
Description: Събития в реално време. Доставени с HMAC подпис.

PaperOffice извиква вашия крайна точка, щом документ, задача, Workspace или процес се променят. Без периодично запитване.

22 типа събития, HMAC-SHA256 подпис, три стратегии за повторен опит и дневник на доставките за всеки опит.

Абониране за първия уебхук Стартиране на първото API извикване

HMAC-SHA256 при всяка доставка До 10 повторения (стандартно 5) Идипотентен по Event-ID

Събития в реално време. Доставени с HMAC подпис.

Собствена инфраструктура в ЕС Вашите данни остават в Европа.
ISO/IEC 27001 (сертифициран) Сигурността е сертифицирана.
24+ години опит Доказано. Стабилно. Бъдеще-ориентирано.

Налични събития

22 типове събития, групирани по сущност

Абонирайте се за отделни събития или използвайте плейсхолдера * за всички.

Документи

document.uploaded Нов документ качен в Workspace
document.created Алиас за document.uploaded (съвместимост)
document.processed OCR/AI-IDP пайплайн успешно завършен
document.edited Документ редактиран: актуализирани са метаданни, тагове или съдържание
document.deleted Документът е изтрит; delete_mode показва trash (Кошче за боклук в Business и Compliance) или instant (окончателно в стандартния)
document.restored Документът е възстановен от кошчето за боклук (Business и Compliance)
document.moved Документ преместен между Workspaces
document.version_created Нова версия на съществуващ документ
document.lifecycle_changed Променен статус на съхранение/архивиране
document.comment_added Създаден коментар към документ
document.note_added Приложена вътрешна бележка
document.tag_added Етикет присвоен на документ
document.legal_hold_placed Активиран правен задържател (непроменяем)
document.legal_hold_released Правният задържател е отменен

Задачи

job.completed Асинхронна задача успешно завършена
job.failed Асинхронна задача окончателно неуспешна
job.progress Обновление на прогреса при дълги задачи

Workspaces

workspace.shared Workspace споделен с потребител или екип
workspace.unshared Достъпът до Workspace е отнет

Задачи

task.created Създадена е нова задача
task.completed Задачата е маркирана като завършена
task.overdue Задачата е излязла от срока за изпълнение

Пейлоад и заглавка

Всяко известие следва една и съща схема

Предсказуемо JSON тяло, фиксирани HTTP заглавки, ISO-8601 UTC времеви маркер.

Тяло на заявката

{
  "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 заглавка на заявката

Заглавка Примерна стойност Значение

Content-Type application/json Винаги JSON, кодирано в UTF-8

User-Agent PaperOffice-Webhook/1.0 Фиксиран идентификатор за бели списъци на защитна стена

X-PaperOffice-Event document.processed Тип на доставеното събитие

X-PaperOffice-Event-ID a3b7f9c1… 128-битов уникален идентификатор. Използвайте го като ключ за идемпотентност.

X-PaperOffice-Subscription-ID 42 Идентификатор на абонамента, който получава събитието

X-PaperOffice-Signature sha256=… HMAC-SHA256 на суровото тяло, кодирано в шестнадесетичен формат

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

Верификация на подписа

Верифицирайте всяко доставяне с HMAC-SHA256

Изчислете HMAC-SHA256 върху суровото тяло на заявката с вашия споделен секрет и сравнете резултата с X-PaperOffice-Signature — задължително с константно време.

Сравнение в константно време
hash_equals, hmac.compare_digest или crypto.timingSafeEqual: Сравнението не трябва да разкрива разлики във времето на изпълнение.
Подписване на тялото на Rohen
Подписът важи за непромененото тяло на заявката. Парсирайте JSON едва след проверката, иначе хешът ще се промени.
Абониране чрез API
POST /latest/webhooks/subscribe с име, URL и събития. Ако оставите тайната празна, PaperOffice я генерира и я връща веднъж.

Удостоверяване и ключове Колекция Postman

Повторен опит и доставка

Три стратегии за повторен опит, до 10 повторения

Изберете политиката за всеки абонамент. Всеки опит се логва с код на състоянието, тяло на отговора и измерване на времето.

Стандартен exponential
Експоненциално (по подразбиране)

Интервалът между опитите се удвоява след всеки неуспешен опит.
linear
Линеен

Интервалът между опитите нараства с фиксирана стъпка.
none
Без

Без повторение, дори при 5xx (изпрати и забрави). Полезно за тестови хукове.

Успех HTTP 2xx в рамките на таймаут прозореца
Макс. повторения До 10 повторения (стандартно 5)
Изтичане на времето 1 000–30 000 ms на опит (стандартно 10 000). Първият опит за доставка е ограничен до 2 или 5 секунди в зависимост от събитието, повторенията използват пълната стойност.
Протокол за доставяне Всеки опит се протоколира; протоколът остава достъпен дори след изтриване на абонамента.

Управление-API

Пет крайни точки под /latest/webhooks/

Създаване, извличане, актуализиране и изтриване на абонаменти — включително тестова крайна точка. Всеки повик използва Bearer токен.

POST /webhooks/subscribe Създаване на абонамент; полезните натоварвания се подписват с HMAC-SHA256 MCP инструментpo-webhooks-subscribe
GET /webhooks/list Извличане на всички уебхук абонаменти за акаунта MCP инструментpo-webhooks-list
POST /webhooks/update Актуализиране на URL, събития, заглавки, политика за повторен опит или активен статус MCP инструментpo-webhooks-update
POST /webhooks/delete Изтриване на абонамент; протоколът за доставяне се запазва MCP инструментpo-webhooks-delete
POST /webhooks/test Изпращане на тестово събитие до абонамент и проверка на доставката MCP инструментpo-webhooks-test

Преглед на MCP сървъра Postman колекция

Сигурност

Засилена от основата

Шест механизма, които се активират при всяка доставка — от страна на PaperOffice и ваша.

HMAC-SHA256
Всяка доставка се подписва с вашия тайен ключ. Сравнението трябва задължително да протича в константно време.
SSRF защита
Частни и вътрешни IP адреси, localhost и облачни метаданни крайници се блокират при абонамент и при изпращане.
Устойчив на DNS rebinding
Целевият адрес се проверява отново по време на доставката.
Препоръчва се HTTPS
Приемат се http и https. За производствена среда препоръчваме HTTPS.
Идипотентност чрез Event ID
Всяко доставяне носи уникална X-PaperOffice-Event-ID. Извършвайте дедупликация на вашата страна.
Пълен протокол на доставката
Всички опити се логират: статус код, отговорно тяло, измерване на времето, съобщение за грешка.

Ограничения

Настройване на поведенето при доставка за всеки абонамент

Всички стойности се задават при създаване или по-късно чрез /webhooks/update — за всеки абонамент, а не за акаунта.

0–10 Повторения при всяка доставка (стандартно 5)
1 000–30 000 мс Таймаут на опит (стандартно 10 000, първи опит 2–5 s)
3 Политики за повторен опит: none, linear, exponential
HMAC-SHA256 Подпис при всяка доставка

Webhooks са налични от план Professional. Кой план е подходящ за вашата конфигурация, вижте в прегледа на цените.

Преглед на цените Удостоверяване и ключове

Въпроси

Често задавани въпроси относно Webhooks

Как да потвърдя доставката?

Изчислете HMAC-SHA256 върху суровия request body, използвайки тайната на вашия абонамент, и сравнете резултата в константно време със заглавката X-PaperOffice-Signature (формат sha256=<hex>). Ако сигнатурата не съвпада, отговорете с HTTP 401 и не обработвайте тялото.

Откъде идва тайната?

При създаване на абонамента чрез POST /latest/webhooks/subscribe. Оставете полето secret празно, за да генерира PaperOffice тайна и да я върне веднъж в отговора. Чрез POST /latest/webhooks/update можете да я замените по всяко време.

Какво се случва, ако моят endpoint не отговори?

Всеки отговор извън HTTP 2xx или таймаут се брои като неуспешен опит. В зависимост от политиката за повторен опит (експоненциална, линейна, без) PaperOffice повтаря доставката до зададения брой повторни опити (0–10, стандартно 5). Всеки опит е записан в дневника на доставките със статус код, отговор и времеви метрики.

Може ли една и съща доставка да пристигне два пъти?

Да, възможно е при повторни опити след таймаут. Затова използвайте дедупликация чрез X-PaperOffice-Event-ID: ID-то е уникално за всяко събитие и може да служи като ключ за идемпотентност във вашата база данни.

Какви събития мога да абонирам?

22 типа събития от четири групи: документи, задачи, работни пространства и действия. Можете да абонирате отделни събития или всички с помощта на плейсхолдера *. Чрез филтри (например workspace_id или pofid) можете допълнително да ограничите абонамента.

В кой план са включени уебхукове?

Уебхуковете са налични от план Professional. Кой план е подходящ за вашата конфигурация, показва ценовата таблица.

Как пристигат таблиците във вебхука?

За полетата с таблици (например стойности на инспекции или редове), document.processed също пренася data.extracted_tables. Списъкът му tables съдържа по един запис за всяко поле на таблица с key, label, columns и rows; всяка клетка има value (число, ако PaperOffice е прочело число, иначе текста както е отпечатан) и value_raw (текста както е отпечатан, или null, ако не е известно). extracted_fields остава непроменено. Всяка доставка съдържа най-много 50 таблици с до 1 000 реда и 40 колони всяка, по 2 000 знака на клетка и общо 512 KB за всички таблици заедно; ако нещо е отрязано, truncated е true, а row_count посочва пълния брой редове. Подписът обхваща цялото тяло на заявката, включително extracted_tables.

Какво е новото в събитието document.processed?

Ново: key_fields вече съдържа и document_number (например номера на фактурата) и publisher (лицето, издало документа), ако PaperOffice ги е прочел. Редовете с позиции пристигат като таблица в data.extracted_tables: таблицата с key __document__content__extraction__line_items (за полетата на агента: _line_items) има по един ред за всяка позиция.

Експлоатация и доверие

Какво екипите на предприятията проверяват преди първия разговор

Договори, сигурност, поддръжка и лимити, всичко свързано на едно място.

Следваща спирка

Какво следва

Препоръчителната следваща стъпка във фунията за разработчици и две подходящи разклонения.

Postman CollectionИмпортиране, тестване и отстраняване на грешки в Postman Publishable KeysБраузърно безопасни ключове за AI артефакти и frontend приложения Първо API извикванеВземете ключа, изпратете заявката, проверете отговора

Назад към началото за разработчици

Събития в реално време. Доставени с HMAC подпис.

22 типове събития, групирани по сущност

Всяко известие следва една и съща схема

Верифицирайте всяко доставяне с HMAC-SHA256

Три стратегии за повторен опит, до 10 повторения

Експоненциално (по подразбиране)

Линеен

Без

Пет крайни точки под /latest/webhooks/

Засилена от основата

Настройване на поведенето при доставка за всеки абонамент

Често задавани въпроси относно Webhooks

Какво екипите на предприятията проверяват преди първия разговор

Какво следва

On-premise DMS за вашата инфраструктура.

Индустриален AI готов в Claude и ChatGPT

Никога не строй сам.

Document Layer вместо инфраструктура.

За партньори, които изграждат своите решения върху PaperOffice.

Собствен хардуер. Собствен Datacenter.

31 безплатни инструмента

PaperOffice PDF Reader