Перейти к основному содержанию
Интеграция Вебхуки предназначена для разработчиков. Она отправляет JSON-событие на выбранный вами HTTPS-адрес каждый раз, когда в Foliant что-то происходит. Так ваша система может на это отреагировать: например, сохранить PDF каждого счёта или забрать готовый экспорт. Вебхуки находятся в бета-версии. Если вы не видите их в разделе Настройки › Интеграции, они пока недоступны для вашего магазина. Чтобы узнать о доступе, обратитесь в поддержку.

События

Подключение вебхуков

  1. В Foliant перейдите в раздел Настройки › Интеграции.
  2. В карточке Вебхуки нажмите Подключить.
  3. Заполните настройки:
  4. Нажмите Подключить.
Позже вы можете изменить URL, секрет и события в разделе Настройки на странице интеграции.

Что содержит каждый запрос

Foliant отправляет запрос POST с телом в формате JSON:

Данные document.generated

  • template: uuid и name шаблона.
  • document_type: invoice, credit_note, quote или пустое значение для других документов.
  • order: его id, name и type (заказы или черновики заказов).
  • refund_id и fulfillment_id, если документ относится к возврату средств или отправке.
  • document_number и issued_at для нумерованных документов.
  • source: способ создания, например download, admin_download, export или email.
  • export: ID экспорта, если документ входит в экспорт.
  • generated_at.

Данные export.completed

  • export: его uuid, order_type, template_uuids, количество orders, orders_skipped (удалённые после выбора) и documents, requested_by (merchant или customer) и completed_at.
  • download_url: ссылка для скачивания экспорта, и download_url_expires_at — время, когда эта ссылка перестанет работать.
  • download_expires_at: время, когда истекает срок действия самого экспорта.
События содержат ID и количества, но не адреса электронной почты клиентов.

Заголовки

Проверка подписи

Подпись — это HMAC-SHA256 в шестнадцатеричном виде от метки времени, точки и исходного тела запроса (<timestamp>.<body>), где ключом служит ваш секрет подписи. Вычислите её на своей стороне и сравните со значением после sha256= в X-Foliant-Signature. Используйте исходное тело точно в том виде, в каком оно получено.

Ответы и повторные попытки

  • Любой ответ 2xx считается успешной доставкой.
  • Если ваш эндпоинт возвращает ошибку 5xx, 408 или 429 либо не отвечает в течение 10 секунд, Foliant повторяет попытку позже, каждый раз ожидая дольше, — всего до 5 попыток.
  • Другие ответы 4xx окончательны: Foliant не повторяет их.
  • Каждое событие доставляется один раз для каждого документа или экспорта. После успешной доставки повторные попытки не отправляют его снова.
Каждая доставка отображается в разделе Активность на странице интеграции, где вы можете нажать Повторить для неудачной доставки. См. Активность интеграции.

Похожие статьи