Перейти до змісту
Огляд Огляд Новини Новини
Поділитися

Webhooks та події

Події в реальному часі. Доставлено з підписом HMAC.

PaperOffice викликає вашу кінцеву точку, як тільки змінюється документ, завдання, робочий простір або задача. Без опитування (polling).

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

HMAC-SHA256 при кожній доставці До 10 повторень (стандартно 5) Імпотентний за ID події

Доступні події

22 типи подій, згруповані за сутністю

Підписуйтесь на окремі події або використовуйте шаблон * для всіх.

Документи

14
  • document.uploaded Новий документ завантажено у робочий простір
  • document.created Аліас для document.uploaded (сумісність)
  • document.processed Успішно завершено OCR/AI-IDP конвеєр
  • document.edited Документ відредаговано: оновлено метадані, теги або вміст
  • document.deleted Документ переміщено до кошика
  • document.restored Документ відновлено з кошика
  • document.moved Документ переміщено між робочими просторами
  • document.version_created Нова версія існуючого документа
  • document.lifecycle_changed Змінено статус зберігання/архівування
  • document.comment_added Створено коментар до документа
  • document.note_added Додано внутрішню нотатку
  • document.tag_added Документу призначено тег
  • document.legal_hold_placed Увімкнено юридичне утримання (незмінний)
  • document.legal_hold_released Юридичне утримання скасовано

Завдання

3
  • job.completed Асинхронне завдання успішно завершено
  • job.failed Асинхронне завдання остаточно завершилося з помилкою
  • job.progress Оновлення прогресу для тривалих завдань

Workspaces

2
  • workspace.shared Робочий простір поділено з користувачем або командою
  • workspace.unshared Знято доступ до робочого простору

Завдання

3
  • 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 сирого тіла запиту, закодований у hex-форматі
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  }'

Перевірка підпису

Перевіряйте кожну доставку за допомогою HMAC-SHA256

Обчисліть HMAC-SHA256 для сирого тіла запиту, використовуючи ваш спільний секрет, і порівняйте результат із X-PaperOffice-Signature — обов'язково з використанням константного часу.

  • Порівняння в константному часі

    hash_equals, hmac.compare_digest або crypto.timingSafeEqual: Порівняння не повинно розкривати різниці у часі виконання.

  • Підписати тіло запиту Rohen

    Підпис дійсний для незміненого тіла запиту. Парсуйте JSON лише після перевірки, інакше хеш буде відрізнятися.

  • Оформлення підписки через API

    POST /latest/webhooks/subscribe з name, url та events. Якщо secret залишити порожнім, PaperOffice згенерує його та поверне одноразово.

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

Три стратегії повторних спроб, до 10 повторень

Обирайте політику для кожної підписки. Кожна спроба логується зі статус-кодом, тілом відповіді та вимірюванням часу.

  • Стандартний exponential

    Експоненційний (за замовчуванням)

    Інтервал між спробами подвоюється після кожної невдалої спроби.

  • linear

    Лінійний

    Інтервал між спробами збільшується на фіксований крок.

  • none

    Без повторів

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

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

Управління-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

Безпека

Захист на рівні архітектури

Шість механізмів, що спрацьовують під час кожної доставки — з боку PaperOffice та з вашого боку.

  • HMAC-SHA256

    Кожна доставка підписується вашим секретним ключем. Порівняння має обов'язково відбуватися за постійний час.

  • Захист від SSRF

    Приватні та внутрішні IP-адреси, localhost та кінцеві точки метаданих хмарних сервісів блокуються під час підписки та диспетчеризації.

  • Захист від DNS-rebinding

    IP-адреса повторно перевіряється під час диспетчеризації та фіксується за допомогою CURLOPT_RESOLVE.

  • Рекомендовано HTTPS

    Приймаються протоколи http та https. Для продуктивної експлуатації рекомендуємо використовувати HTTPS.

  • Ідемпотентність через Event-ID

    Кожна доставка містить унікальний ідентифікатор X-PaperOffice-Event-ID. Здійснюйте дедуплікацію на вашому боці.

  • Повний журнал доставки

    Усі спроби логується: код стану, тіло відповіді, вимірювання часу, повідомлення про помилку.

Обмеження

Налаштування поведінки доставки для кожного підписки

Усі значення встановлюються при створенні або пізніше через /webhooks/update — для кожного підписки, а не для облікового запису.

  • 0–10 Повторні спроби на одну доставку (за замовчуванням 5)
  • 1.000–30.000 мс Тайм-аут на одну спробу (за замовчуванням 10.000)
  • 3 Політики повторних спроб: none, linear, exponential
  • HMAC-SHA256 Підпис при кожній доставці

Webhooks доступні починаючи з плану Professional. Який план підходить для вашої конфігурації, показано в огляді цін.

Відео

Вебхуки в дії

Подивіться, як PaperOffice вебхуки працюють на практиці — у відео.

Вебхуки в дії

Запитання

Часті запитання щодо вебхуків

Як я можу підтвердити доставку?

Обчисліть 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. Який план підходить для вашого налаштування, можна дізнатися з огляду цін.

Де ви хочете спробувати PaperOffice?

Комп'ютер і смартфон підключені: робочий простір на комп'ютері, захоплення на телефоні.

Ваша пробна версія готова

З чого ви хочете почати?

Повний робочий простір оптимізовано для комп'ютера. Мобільна версія підходить для захоплення, перевірки та затвердження документів.

app.paperoffice.ai

Почати на комп'ютері

Ми надішлемо ваше особисте посилання для входу на електронну пошту.

Зареєструватися безкоштовно Відкрити застосунок Застосунок PaperOffice Повний продукт: веб, комп’ютер і мобільні пристрої. Захоплюйте, організовуйте, шукайте документи та працюйте з ними разом із командою. Потрібен безкоштовний обліковий запис Відкрити Playground Playground Вибрані функції одразу — без реєстрації, з обмеженим демо-ключем API. Без реєстрації, але з обмеженим демо-ключем API