API Reference
Start typing to search…

Посібник з використання вебхуків

Вебхуки дозволяють вашим системам отримувати оновлення в реальному часі, коли в RO App відбуваються певні події. Ці оновлення надсилаються як HTTP POST запити на вказаний вами ендпоінт. Завдяки нашому Webhooks API ви можете автоматизувати робочі процеси, інтегруватися з сторонніми додатками та динамічно реагувати на події в нашій системі.

Як це працює

  1. Відбувається подія: У нашій системі ініціюється попередньо визначена подія (наприклад, створення замовлення, оновлення статусу).
  2. Надсилається вебхук-пейлоуд: Наша система надсилає HTTP POST запит на ваш ендпоінт з деталями події у форматі JSON.
  3. Обробка пейлоуду: Ваша система обробляє дані для подальших дій або інтеграцій.

Реєстрація вебхука

Щоб почати використовувати вебхуки, виконайте наступні кроки:

Крок 1: Пепейдіть до налаштувань вебхуків

Крок 2: Створіть вебхук

  • Натисніть "+ Вебхук".
  • Введіть наступні дані:
    • URL ендпоінту (URL, на який будуть надіслані дані за подією)
    • Опис
    • Події (виберіть події, про які ви хочете отримувати оновлення за допомогою вебхуків).
    • Натисніть кнопку "Створити"

Переконайтеся, що ваш ендпоінт доступний та використовує HTTPS для безпечної передачі даних.

Підтримувані події

Нижче наведено перелік подій, на які ви можете підписатися.

Завдання

Task.Created — Ініціюється, коли завдання створено.
Task.Completed — Ініціюється, коли завдання позначено як виконане.
Task.Reopened — Ініціюється, коли завдання відкрито повторно.
Task.Deadline.Changed — Ініціюється, коли кінцевий термін завдання змінено.
Task.Assignee.Changed — Ініціюється, коли виконавця завдання змінено.
Task.Deleted — Ініціюється, коли завдання видалено.

Звернення

Lead.Created — Ініціюється, коли звернення створено.
Lead.Status.Changed — Ініціюється, коли статус звернення змінився.
Lead.Client.Changed — Ініціюється, коли клієнт у зверненні змінився.
Lead.Type.Changed — Ініціюється, коли тип звернення змінився.
Lead.Deadline.Changed — Ініціюється, коли кінцевий термін звернення змінився.
Lead.Location.Changed — Ініціюється, коли локація звернення змінилася.
Lead.Manager.Changed — Ініціюється, коли менеджер звернення змінився.
Lead.Deleted — Ініціюється, коли звернення видалено.

Розрахунки та Замовлення

Order.Created —  Ініціюється, коли замовлення створено.
Order.Type.Changed — Ініціюється, коли тип замовлення змінився.
Order.Status.Changed — Ініціюється, коли статус замовлення змінився.
Order.Client.Changed — Ініціюється, коли клієнт у замовленні змінився.
Order.Manager.Changed — Ініціюється, коли менеджер замовлення змінився.
Order.Assignee.Changed —  Ініціюється, коли виконавець замовлення змінився.
Order.Deadline.Changed — Ініціюється, коли кінцевий термін замовлення змінився.
Order.Amount.Changed — Ініціюється, коли загальна сума замовлення змінилася.
Order.Location.Changed — Ініціюється, коли замовлення переміщено до іншої локації.
Order.Approval.Accepted —  Ініціюється, коли розрахунок або замовлення прийнято клієнтом.
Order.Approval.Declined — Ініціюється, коли розрахунок або замовлення відхилено клієнтом.
Order.Deleted — Ініціюється, коли замовлення видалено.

Клієнти

Client.Created — Ініціюється, коли клієнта створено.
Client.Deleted — Ініціюється, коли клієнта видалено.
CustomerFeedback.Created — Ініціюється, коли отримано новий відгук від клієнта.

Рахунки

Invoice.Created — Ініціюється, коли рахунок створено.
Invoice.Deleted — Ініціюється, коли рахунок видалено.

Інші події

Comment.Created — Ініціюється, коли новий коментар створено.
Attachment.Created — Ініціюється, коли нове файл або зображення прикріплено до об'єкта (завдання, звернення, замовлення тощо).
Auth.Login — Ініціюється, коли співробітник авторизується в акаунті.

Webhook Payload

Коли подія активується, ми надсилаємо JSON-повідомлення на ваш ендпоінт. Нижче наведено приклад структури повідомлення:

{
  "id": "9cba80cc-93b5-459b-bfd3-445e724dafc5",
  "created_at": "2024-12-05T11:31:39.440424Z",
  "created_at_ts": 1733398299.440424,
  "event_name": "Order.Status.Changed",
  "context": {
    "object_id": 50699833,
    "object_type": "order"
  },
  "metadata": {
    "new": {
      "id": 267312
    },
    "old": {
      "id": 393648
    },
    "order": {
      "id": 50699833,
      "name": "AB0300"
    }
  },
  "employee": {
    "id": 200206,
    "full_name": "John Doe",
    "email": "[email protected]"
  }
}

Поля

  • id — унікальний ідентифікатор вебхука
  • created_at — дата запиту у форматі ISO 8601
  • created_at_ts — дата запиту у форматі timestamp.
  • event_name — назва події
  • context — контект, у якому відбулася подія
  • metadata — корисна інформація про подію
  • employee — хто ініціював подію

Безпека вебхуків

Щоб забезпечити цілісність та автентичність даних вебхуків, кожен запит включає заголовок X-Signature. Цей заголовок містить SHA-256 хеш, створений на основі ідентифікатора вебхука та вашого секретного ключа. Ви можете використовувати цей підпис для перевірки, що дані вебхука надійшли саме від нашої системи та не були змінені.

Обробка помилок і повторні спроби

Якщо ваш ендпоінт не відповідає кодом стану 2XX, ми повторно надішлемо вебхук наступним чином:

  • 1-а спроба: через 5 секунд.
  • 2-а спроба: через 10 секунд.
  • 3-я спроба: через 15 секунд.

Якщо ми не отримаємо відповідь 200 OK після кількох повторних спроб протягом 1 години, вебхук буде автоматично відключено. Це дозволяє уникнути впливу нефункціональних ендпоінтів на продуктивність системи.

Щоб знову активувати вебхук, вам потрібно усунути проблему та вручну його активувати на сторінці налаштувань вебхуків.

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