Вебхуки и события

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

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

22 типа событий, подпись HMAC-SHA256, три стратегии повторной попытки и журнал доставки для каждой попытки.

Подписаться на первый webhook Запустить первый вызов API

HMAC-SHA256 при каждой доставке До 10 повторений (стандартно 5) Идемпотентно по ID события

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

Собственная инфраструктура ЕС Ваши данные остаются в Европе.
ISO/IEC 27001 (сертифицировано) Безопасность сертифицирована.
SOC 2 Type II в подготовке Международные стандарты аудита.
Более 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 Включен Legal Hold (неизменяемый)
document.legal_hold_released Legal Hold отменен

Задания

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 ID подписки, получающей событие

X-PaperOffice-Signature sha256=… HMAC-SHA256 от необработанного тела запроса, закодированное в hex

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: Сравнение не должно раскрывать различия во времени выполнения.
Подписать исходное тело запроса
Подпись действует для неизменного тела запроса. Парсите JSON только после проверки, иначе хеш изменится.
Оформление подписки через API
POST /latest/webhooks/subscribe с полями name, url и events. Если secret оставлен пустым, PaperOffice генерирует его и возвращает однократно.

Аутентификация и ключи Коллекция Postman

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

Три стратегии повторных попыток, до 10 повторов

Выберите политику для каждой подписки. Каждая попытка логируется с кодом состояния, телом ответа и замером времени.

По умолчанию exponential
Экспоненциальная (по умолчанию)

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

Интервал между попытками увеличивается на фиксированный шаг.
none
Нет

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

Успех HTTP 2xx в пределах окна тайм-аута
Макс. повторные попытки До 10 повторных попыток (по умолчанию 5)
Тайм-аут 1 000–30 000 мс на попытку (по умолчанию 10 000). Первая попытка доставки ограничена в зависимости от события 2 или 5 секундами, повторные попытки используют полное значение.
Журнал доставки Каждая попытка логируется; журнал сохраняется даже после удаления подписки.

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

Пять конечных точек в /latest/webhooks/

Создание, просмотр, обновление и удаление подписок — включая тестовую конечную точку. Каждый запрос использует Bearer-токен.

POST /webhooks/subscribe Создание подписки; полезная нагрузка подписывается с помощью HMAC-SHA256 Инструмент MCPpo-webhooks-subscribe
GET /webhooks/list Просмотр всех вебхук-подписок аккаунта Инструмент MCPpo-webhooks-list
POST /webhooks/update Обновление URL, событий, заголовков, политики повторных попыток или статуса активности Инструмент MCPpo-webhooks-update
POST /webhooks/delete Отменить подписку; журнал доставки сохраняется Инструмент MCPpo-webhooks-delete
POST /webhooks/test Отправить тестовое событие на подписку и проверить доставку Инструмент MCPpo-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 с)
3 Политики повторных попыток: none, linear, exponential
HMAC-SHA256 Подпись при каждой доставке

Вебхуки доступны начиная с плана Professional. Какой план подходит для вашей конфигурации, вы можете увидеть в таблице цен.

Посмотреть цены Аутентификация и ключи

Вопросы

Часто задаваемые вопросы о вебхуках

Как я могу подтвердить доставку?

Вычислите HMAC-SHA256 по необработанному телу запроса с использованием секрета вашей подписки и сравните результат в константном времени со значением заголовка X-PaperOffice-Signature (формат sha256=<hex>). Если подпись не совпадает, ответьте HTTP 401 и не обрабатывайте тело.

Откуда берется секрет?

При создании подписки через POST /latest/webhooks/subscribe оставьте поле secret пустым, и PaperOffice сгенерирует секретный ключ, который будет возвращен однократно в ответе. Вы можете заменить его в любое время с помощью POST /latest/webhooks/update.

Что происходит, если мой конечный пункт не отвечает?

Любой ответ, отличный от 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 КБ для всех таблиц вместе; если что-то было обрезано, 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) содержит одну строку на каждую позицию.