Webhooks: миттєві сповіщення ваших систем про події (бета)

Функція в бета-режимі, вмикається в Налаштування → Ранні функції (у меню — «Експериментальні функції»). Докладніше — Експериментальні функції.

Webhook — це «дзвінок» від OneB Invoice вашій системі: щойно сталася подія (створено рахунок, змінився статус, додано клієнта), ваш сайт чи CRM дізнається про це відразу, без постійних опитувань. Як і публічне API, функція розрахована на роботу разом із розробником.

Де це в застосунку: Налаштування → Webhooks.

Як створити вебхук

Увімкніть «Webhooks» у Налаштування → Ранні функції.
Відкрийте Налаштування → Webhooks і натисніть «Створити вебхук».
Заповніть форму:
- URL — адреса вашої системи, яку надасть розробник. Приймаються лише адреси на https.
- Події — позначте, про що повідомляти.
- Заголовки (необовʼязково) — до 10 власних службових заголовків запиту, якщо їх вимагає ваша система.
- Опис — для себе, щоб памʼятати призначення.
Натисніть «Створити». Одразу після цього система покаже секрет підпису — збережіть його, бо показується він один раз.

1.00

Які події можна отримувати

Зараз доступні дев'ять подій, згрупованих за темами. У формі вони підписані англійською — нижче відповідність.

Документи

Invoice Created — документ створено (у застосунку, через API або автоматично з Prom.ua).
Invoice Updated — документ оновлено.
Invoice Status Changed — змінився статус документа. У повідомленні передається і попередній статус.
Invoice Deleted — документ видалено (передається лише його ідентифікатор).

У кожному повідомленні про документ є його джерело: створено користувачем у застосунку, через API чи інтеграцією (наприклад, Prom.ua). Так ваша система може обробляти лише «свої» документи, а решту пропускати. Докладніше — у статті Публічне API та API-ключі.

Клієнти

Client Created, Client Updated, Client Deleted — клієнта додано, змінено, видалено. Зручно для синхронізації бази з CRM.

Платежі

Payment Linked, Payment Unlinked — платіж із OneB Finance привʼязано до документа або відвʼязано від нього.

Як зловити момент, коли рахунок виставили клієнту

Типовий сценарій: ваша система створює рахунок як чернетку, а бухгалтер перевіряє його і натискає «Поділитись». Саме в цей момент документ переходить зі статусу «Чернетка» в «Очікує», і ви отримуєте подію Invoice Status Changed з попереднім статусом «Чернетка». Це і є сигнал «рахунок виставлено».

Памʼятайте, що редагування вже виставленого документа повертає його в чернетку (див. Статуси документів): ви отримаєте подію про перехід в «Чернетку», а після повторного «Поділитись» — знову про виставлення. Ваша система має бути готова до такого «кроку назад».

Як дізнатися, що рахунок оплачено

Будь-який перехід рахунка в «Оплачено» породжує подію Invoice Status Changed з попереднім статусом «Очікує» — незалежно від того, як саме надійшла оплата:

клієнт оплатив онлайн через платіжний сервіс (plata by mono, LiqPay, Stripe, PayPal) — подія приходить одразу після підтвердження від сервісу;
платіж підтягнувся з OneB Finance або його привʼязали вручну — крім зміни статусу, ви отримаєте ще й Payment Linked;
бухгалтер позначив оплату вручну або статус змінила інша інтеграція.

У стрічці сповіщень і в історії статусів документа теж зʼявляється відповідний запис. Тож будувати логіку «гроші прийшли» можна на події зміни статусу; періодичну звірку через публічне API варто лишити лише як страховку на випадок, якщо ваш сервер був недоступний довше, ніж тривають повторні спроби доставки.

Інші випадки, коли статус змінюється сам, зібрані у статті Чому статус документа змінився сам.

Секрет і перевірка підпису

Разом із кожним запитом ми надсилаємо підпис — контрольну суму тіла повідомлення, обчислену з вашим секретом. Ваша система має порахувати таку саму суму й порівняти.

Навіщо це потрібно: адреса вашого обробника рано чи пізно стає відомою, і на неї може постукати хто завгодно, вдаючи OneB Invoice. Перевірка підпису — єдиний спосіб переконатися, що повідомлення справді від нас і його не змінили дорогою. Просити розробника «просто приймати все підряд» не варто: без перевірки чужий запит зможе, наприклад, позначити у вашій системі неоплачений рахунок як оплачений.

Секрет показується один раз — при створенні вебхука. Якщо його втратили або є підозра, що він потрапив не в ті руки, натисніть «Перегенерувати секрет» у картці вебхука: система покаже нове значення, а старе одразу перестане діяти. Не забудьте оновити його у своїй системі, інакше вона почне відкидати наші запити.

Разом із підписом у кожному повідомленні передається назва події та ідентифікатор вебхука — у тому самому форматі, що й в API, тож розробник може звірити, від якого саме вебхука прийшло повідомлення.

Журнал доставок

У картці вебхука є кнопка «Доставки» — стрічка того, що і з яким результатом ми надсилали. Для кожного запису видно:

статус — успіх, очікує, повтор або помилка;
подію;
код відповіді вашого сервера;
дату і час доставки;
кількість спроб;
ідентифікатор документа, якщо подія стосується документа.

Це перше місце, куди варто дивитись, коли «нічого не приходить»: якщо в журналі порожньо — подія не настала або вебхук вимкнено; якщо є записи з помилкою і кодом відповіді — проблема на боці вашої системи.

Ручної кнопки «надіслати ще раз» немає. Повторні спроби виконуються автоматично (див. нижче), а щоб отримати подію ще раз, треба повторити саму дію — наприклад, ще раз змінити статус документа. Якщо потрібно просто дістати актуальні дані, простіше запитати їх через публічне API.

Що відбувається автоматично

Ми робимо до 5 спроб доставки з наростаючою паузою: приблизно 10 секунд, 1 хвилина, 5 хвилин, 30 хвилин і 2 години. Після п'ятої невдалої спроби доставка позначається як помилка і більше не повторюється.
Успішною вважається будь-яка «зелена» відповідь вашого сервера. На відповідь дається 15 секунд — довга обробка на вашому боці зчитається як невдача, тож правильно спершу швидко відповісти, а вже потім обробляти.
Перед кожною спробою адреса перевіряється заново: адреси у внутрішніх мережах відхиляються, а переадресації не виконуються — якщо ваш сервер відповідає редіректом, доставка вважається невдалою.

Обмеження й нюанси

Вебхуки — рання (експериментальна) функція: поки ви не увімкнете «Webhooks» у Налаштування → Ранні функції, пункту меню просто не буде. Доступ до вебхуків також входить не в кожен тарифний план — на пункті меню може зʼявитись іконка корони. Див. Експериментальні функції і Тарифний план і ліміти.

Створювати, редагувати, вимикати й видаляти вебхуки, а також дивитись журнал доставок може лише користувач із правами адміністратора робочого простору. Див. Користувачі й ролі робочого простору.

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

Вебхук можна тимчасово вимкнути, не видаляючи: у картці є перемикач, і в списку такий вебхук позначається міткою «Вимкнено». Поки він вимкнений, події для нього не надсилаються і не накопичуються — пропущене потім не «дошлеться».

Порядок доставки двох подій, що сталися майже одночасно (наприклад, «оновлено» і «змінився статус»), не гарантується. Розробникові варто орієнтуватись на дані всередині повідомлення, а не на черговість отримання.

Часті питання

Створив вебхук, але нічого не приходить. Перевірте: чи увімкнений вебхук, чи позначені потрібні події, чи є записи в журналі доставок і який код відповіді повертає ваш сервер.

У журналі статус «повтор» — це погано? Ні, це означає, що спроба не вдалась і система спробує ще раз за розкладом. Тривожно, якщо дійшло до статусу «помилка».

Клієнт оплатив карткою онлайн — яка подія прийде? Invoice Status Changed з попереднім статусом «Очікує» і новим «Оплачено», одразу після підтвердження від платіжного сервісу. Якщо оплата пройшла через OneB Finance, додатково прийде Payment Linked.

Я загубив секрет. Перегенеруйте його в картці вебхука і одразу пропишіть нове значення у своїй системі.

Чи можна надіслати подію повторно вручну? Ні. Повтори лише автоматичні; щоб отримати подію знову, треба повторити саму дію.

Скільки вебхуків можна створити? Скільки потрібно. Для різних систем краще робити окремі вебхуки — кожен зі своїм URL і власним набором подій.

Як дізнатися, що документ створила саме моя система, а не бухгалтер? За джерелом документа у повідомленні: «API» для документів з API-ключа, «користувач» для створених у застосунку, назва інтеграції для решти.

Що може змінитися

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