Вебхуки Shopify — це один із найпростіших способів інтегрувати магазин із зовнішніми системами, такими як ERP, CRM, платформи виконання замовлень (fulfillment), бухгалтерське ПЗ або кастомні внутрішні сервіси.
Вони чудово працюють — доки приймаюча система не стає недоступною.
Поширена помилка — вважати, що Shopify намагатиметься доставити вебхук нескінченно. Насправді доставка вебхуків має часові ліміти, ліміти повторних спроб (ретраїв) та пороги помилок. Якщо ваш кінцевий вузол (endpoint) залишається недоступним занадто довго, події можуть затримуватися, втрачатися або вимагати ручного відновлення.
У цій статті ми розберемо, чому відбуваються збої в доставці вебхуків, порівняємо популярні стратегії вирішення цієї проблеми та розглянемо архітектурний патерн під назвою **API Proxy Queueing** (Черги на рівні API-проксі), який дозволяє значно підвищити надійність вебхуків без необхідності будувати власну інфраструктуру черг.
---
## Розуміння доставки вебхуків Shopify
Коли Shopify надсилає подію вебхуку, наприклад, `orders/create`, він очікує успішної HTTP-відповіді від приймаючого кінцевого вузла.
Типові сценарії збоїв включають:
* Приймаючий сервер повертає помилку `5xx`.
* Приймаючий сервер повертає помилку `429 Too Many Requests`.
* Приймаючий сервер відповідає занадто повільно.
* Проблеми з мережевим підключенням заважають доставці.
Shopify автоматично повторює спроби доставки вебхуків, які завершилися збоєм, використовуючи графік повторів та експоненціальний бекофф (exponential backoff). Хоча ці повторні спроби допомагають впоратися з тимчасовими збоями, вони не призначені для заміни повноцінної та надійної черги.
Розглянемо типовий сценарій:
* ERP-система перебуває офлайн під час запланованої міграції бази даних.
* Флеш-сейл генерує сотні замовлень.
* Shopify продовжує спроби доставки.
* ERP залишається недоступною так довго, що ліміт спроб Shopify вичерпується.
Результат — затримка синхронізації, відсутність записів та потреба у ручному відновленні даних.
Головна проблема проста:
> Здатність Shopify успішно доставляти вебхуки безпосередньо залежить від доступності вашого кінцевого вузла в момент доставки.
---
## Чому прямі інтеграції стають єдиною точкою відмови (Single Point of Failure)
Типова інтеграція виглядає так:
```text
Shopify Webhook
│
▼
ERP / CRM
```
Ця архітектура проста, але вразлива.
Кожен вебхук залежить від:
* Доступності додатку
* Доступності бази даних
* Надійності мережі
* Пропускної здатності інфраструктури
Якщо ламається будь-який із цих компонентів, доставка вебхуку також може зазнати збою.
Для критично важливих бізнес-процесів (таких як обробка замовлень або синхронізація залишків) це створює невиправданий ризик.
---
## Популярні рішення
### Варіант 1: Черга всередині додатку
Поширений підхід полягає в тому, щоб миттєво підтвердити отримання вебхуку та помістити його у внутрішню чергу.
```text
Shopify
│
▼
Додаток
│
▼
Черга (Redis / DB)
│
▼
Фоновий воркер (Worker)
│
▼
ERP
```
**Переваги**
* Легко інтегрувати в існуючий додаток.
* Бізнес-логіка залишається в одній кодовій базі.
* Добре працює для багатьох сценаріїв.
**Обмеження**
* Додаток все одно має бути онлайн, щоб прийняти вебхук.
* Збої в роботі бази даних можуть завадити збереженню даних у чергу.
* Перевантаження інфраструктури може вплинути на прийом нових вебхуків.
Черга захищає внутрішні системи, але публічний вузол вашого додатку все одно залишається критичною залежністю.
---
### Варіант 2: Виділена хмарна інфраструктура черг
Багато організацій використовують керовані хмарні сервіси.
Приклад:
```text
Shopify
│
▼
API Gateway
│
▼
Lambda-функція
│
▼
SQS-черга
│
▼
Воркер (Worker)
│
▼
ERP
```
**Переваги**
* Висока масштабованість.
* Надійне зберігання повідомлень.
* Чудова відмовостійкість.
**Обмеження**
* Необхідно налаштувати кілька різних сервісів.
* Потрібні знання з управління хмарною інфраструктурою.
* Зростають операційні витрати та складність моніторингу.
* Витрати розподіляються між різними сервісами.
Для великих команд це часто найкращий вибір, але для менших проектів він може бути надлишковим.
---
## Патерн API Proxy Queueing (Черги на рівні API-проксі)
Альтернативний підхід полягає в розміщенні виділеного проксі-шару між Shopify та вашою кінцевою системою.
```text
Shopify
│
▼
API-проксі
│
▼
Черга
│
▼
Воркери
│
▼
ERP / CRM
```
Замість прямої пересилки запитів проксі:
1. Приймає вебхук.
2. Валідує запит.
3. Зберігає корисне навантаження (payload) у надійній черзі.
4. Миттєво повертає Shopify успішну відповідь.
5. Доставляє дані асинхронно.
Це повністю відокремлює отримання вебхуків від доступності бізнес-систем.
### Типовий процес (Flow)
```text
Shopify Webhook
│
▼
┌──────────────┐
│ API-проксі │
└──────────────┘
│
▼
┌──────────────┐
│ Черга │
└──────────────┘
│
▼
┌──────────────┐
│ Воркер │
└──────────────┘
│
▼
┌──────────────┐
│ ERP / CRM │
└──────────────┘
```
Якщо ERP стає недоступною, події залишаються в черзі, поки доставка не завершиться успішно або не буде вичерпано налаштований ліміт спроб.
---
## Порівняння підходів
<table>
<thead>
<tr>
<th>Підхід</th>
<th>Складність налаштування</th>
<th>Власність інфраструктури</th>
<th>Вирішує проблему падіння ERP</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>Прямий кінцевий вузол</b></td>
<td>Низька</td>
<td>Немає</td>
<td>❌</td>
</tr>
<tr>
<td><b>Черга всередині додатку</b></td>
<td>Середня</td>
<td>Команда додатку</td>
<td>⚠️</td>
</tr>
<tr>
<td><b>Хмарна інфраструктура</b></td>
<td>Висока</td>
<td>Внутрішня команда</td>
<td>✅</td>
</tr>
<tr>
<td><b>API Proxy Queueing</b></td>
<td>Низька</td>
<td>Керований провайдер</td>
<td>✅</td>
</tr>
</tbody>
</table>
Жоден з підходів не є універсально найкращим.
Правильний вибір залежить від операційних вимог, розміру команди та вподобань щодо управління інфраструктурою.
---
## Питання безпеки
При додаванні проміжного шару безпека вебхуків залишається пріоритетом.
Для інтеграцій із Shopify це зазвичай включає:
* Перевірку підпису `X-Shopify-Hmac-Sha256`.
* Захист API-ключів та доступів.
* Обмеження неавторизованих запитів.
* Ведення логів аудиту.
Перш ніж використовувати будь-як проксі-рішення, перевірте:
* Як саме перевіряється автентичність вебхуків.
* Чи шифрується корисне навантаження під час передачі.
* Де і як зберігаються дані в черзі.
* Які правила зберігання та видалення даних діють.
Надійність не повинна досягатися за рахунок зниження безпеки.
---
## Приклад реалізації з MirApi
Однією з реалізацій цього патерну є MirApi, яка виступає як керований проксі та сервіс доставки вебхуків.
Замість того, щоб направляти Shopify безпосередньо на вашу ERP, ви налаштовуєте Shopify на надсилання вебхуків через проксі.
Проксі-сервер:
* Приймає вхідні запити.
* Додає пейлоади в чергу.
* Повторює спроби доставки у разі збоїв.
* Опціонально надсилає зворотні виклики (callbacks) про статус доставки.
### Обмеження конфігурації Shopify
Конфігурація вебхуків Shopify дозволяє вказувати лише адресу призначення (URL).
Кастомні заголовки (headers) не можна налаштувати через інтерфейс Shopify.
Щоб обійти це обмеження, MirApi дозволяє передавати параметри маршрутизації та спроб доставки безпосередньо в параметрах URL (query parameters).
Приклад:
```http
https://proxy.mirapi.io/?mirapi_key=your_key&target=https%3A%2F%2Fyour-crm.com%2Fapi%2Forders&retry_count=10&retry_delay=5s
```
Параметри включають:
| Параметр | Призначення |
| :--- | :--- |
| `mirapi_key` | Авторизує запит у проксі |
| `target` | Кінцева адреса призначення |
| `retry_count` | Максимальна кількість спроб доставки |
| `retry_delay` | Початкова затримка між спробами |
Оскільки вкладені URL-адреси передаються як query-параметри, вони обов'язково мають бути закодовані (URL-encoded).
---
## Опціональні статус-вебхуки (Delivery Callbacks)
Деякі інтеграції потребують інформації про статус доставки повідомлень.
Для цього можна налаштувати зворотний виклик (callback):
```http
https://proxy.mirapi.io/?mirapi_key=your_key&target=https%3A%2F%2Fyour-crm.com%2Fapi%2Forders&callback=https%3A%2F%2Fyour-app.com%2Fwebhook-status
```
Коли доставка завершується успішно або остаточно зазнає збою, на вказаний callback-URL надсилається звіт про результат.
Якщо вам не потрібно відстежувати статус доставки в реальному часі, цей параметр можна опустити.
---
## Трансформація корисного навантаження (Payload Transformation)
Частою проблемою інтеграції вебхуків є невідповідність схем даних.
Shopify надсилає детальні JSON-структури, тоді як сторонні системи зазвичай вимагають:
* Інших назв полів
* Пласкої (flattened) структури
* Меншого набору даних
* Кастомних форматів
Деякі платформи API-проксі підтримують трансформацію пейлоаду перед його доставкою.
Це дозволяє уникнути розгортання окремих сервісів трансформації або написання кастомного посередницького ПЗ (middleware).
Типові сценарії використання:
* Перетворення замовлення Shopify у формат, сумісний з вашою ERP.
* Мапінг полів відповіді у зворотні виклики (callbacks).
* Фільтрація непотрібних даних для економії трафіку та підвищення безпеки.
---
## Плюси та мінуси API Proxy Queueing
Як і будь-яке архітектурне рішення, використання проксі-черги має свої компроміси.
### Переваги
* Швидке впровадження.
* Менше турбот про сервери та черги (managed infrastructure).
* Вбудовані механізми автоматичних спроб (retries).
* Надійний захист від тимчасових збоїв та пікових навантажень.
* Зручний моніторинг через дашборд та систему логів.
### Обмеження
* З'являється залежність від стороннього сервісу (third-party dependency).
* Додається ще один мережевий перехід (extra hop).
* Надійність черги залежить від архітектури обраного провайдера.
* Використання специфічних функцій провайдера може ускладнити майбутню міграцію.
Розуміння цих факторів допоможе визначити, чи підходить кероване рішення для вашого проекту.
---
## Висновок
Надійність доставки вебхуків часто вважають проблемою самого додатку, хоча насправді це інфраструктурне питання.
Прямі інтеграції чудово працюють, коли всі сервери онлайн. Але реальні системи зазнають збоїв, проводять технічні роботи, стикаються з лімітами запитів та іншими непередбачуваними помилками.
Додавання надійного буферного шару між Shopify та вашими внутрішніми системами суттєво мінімізує операційні ризики.
Незалежно від того, будуєте ви чергу самостійно в хмарі чи використовуєте готовий інструмент, головний архітектурний принцип залишається незмінним:
> Швидко прийми, надійно збережи, оброби асинхронно.
Для команд, які хочуть використовувати цей патерн без зайвих витрат на налаштування власних черг, керовані платформи API-проксі, такі як MirApi, пропонують готове та просте в інтеграції рішення.
---
> **Примітка:** Якщо ви хочете протестувати цей патерн без написання додаткового коду, ви можете створити [безкоштовний акаунт MirApi](https://mirapi.io/?utm_source=itblog&utm_campaign=content) (включає 10 000 безкоштовних запитів на місяць, кредитна картка не потрібна).
