Исходящие вебхуки

Вебхуки заставляют FreeMaint отправлять POST на подконтрольный вам URL сразу же, как что-то произошло, чтобы другая система (ERP, биллинг, склад, бухгалтерия, чат-канал) оставалась в согласии без ручного перевода данных. Настройка в /company-settings/webhooks. На тарифе Starter лимит 100 доставок в день; на Business и выше — без ограничений. Полный справочник по полезной нагрузке — в разделе «API и GraphQL > Вебхуки».

Доступные события

• work_order.created — создан заказ-наряд
• work_order.completed — заказ-наряд переведён в «Завершён»
• work_order.status_changed — заказ-наряд перешёл в любой статус; work_order.completed при этом тоже срабатывает
• request.created — подана заявка на обслуживание
• request.status_changed — заявка согласована, отклонена или отменена
• part.low_stock — запчасть опустилась до точки заказа или ниже
• part.out_of_stock — запчасть закончилась
• part.low_stock_summary — раз в сутки: запчасти на точке заказа или ниже, включая те, что ни разу не двигались
• part.out_of_stock_summary — раз в сутки: запчасти с нулевым остатком
• part.consumed — запчасть списана на заказ-наряд или возвращена с него
• compliance.chain_divergence — нарушена хеш-цепочка аудита (Enterprise)
• asset.downtime_started — открыт простой оборудования
• asset.downtime_ended — простой оборудования закрыт
• report.daily_summary — завершённые за день работы, раз в сутки в выбранный вами час
• purchase_order.created — создан заказ на закупку
• purchase_order.status_changed — заказ на закупку сменил статус (утверждён, заказан, отменён…)
• purchase_order.received — по заказу на закупку принята поставка, включая частичные

Семантика доставки

• POST с телом JSON: { event, timestamp, data }
• Заголовок X-FreeMaint-Signature — t=<секунды unix>,v1=<hex>, где v1 — это HMAC-SHA256 строки «<t>.<сырое тело>» с ключом, равным секрету вашего вебхука. Проверяйте его в каждом запросе, по сырому телу
• Дополнительно отправляются X-FreeMaint-Event и X-FreeMaint-Delivery-Id
• Сетевые ошибки и 5xx повторяются до 3 раз с экспоненциальной задержкой (примерно 2, 4 и 8 секунд); 4xx — окончательный отказ, повтора не будет
• Каждая попытка пишется в журнал вебхука со статусом, кодом ответа и числом попыток — и любую завершённую доставку оттуда можно отправить повторно
• Необязательные фотографии: при включённой опции «Включать фотографии» события "work_order" и "request" содержат до 4 ссылок на изображения в поле "photos", действующих 7 дней для любого, у кого они есть, — включайте только для конечной точки под вашим контролем

Настройка

1. Откройте /company-settings/webhooks — Требуется право на настройки компании или право «Управление интеграциями».
2. Нажмите «Добавить вебхук» — Задайте имя, URL на https:// и отметьте нужные события.
3. Скопируйте секрет подписи — Он показывается ОДИН раз при создании. Позже можно выпустить новый через «Сменить секрет» — старый при этом перестанет действовать.
4. Следите за доставками — Откройте историю доставок вебхука, чтобы убедиться, что события приходят, и переотправить то, что не прошло.

Лимиты по тарифам

• Starter — 100 доставок в день на компанию (счётчик обнуляется в 00:00 UTC)
• Business — без ограничений
• Enterprise — без ограничений
• Счётчик считает ПОПЫТКИ: три вебхука на одно событие расходуют три единицы