Webhooks

Webhooks дозволяють вам отримувати оновлення в режимі реального часу від Meshy, коли ваші API-задачі завершуються або змінюють статус. Після налаштування Meshy надсилатиме POST-запити з корисним навантаженням подій у форматі json на вказані вами URL-адреси.

Чому варто створювати Webhooks

Використання webhooks має кілька переваг, особливо щодо автоматичної перевірки статусів API-задач. Webhooks вимагають менше зусиль і витрат, ніж постійний опитування API для отримання оновлень статусу задач. Webhooks також дозволяють отримувати оновлення майже в режимі реального часу та зрештою масштабуються краще, ніж опитування API. Це також дозволяє вам краще керувати своїми лімітами швидкості, особливо якщо ви постійно опитуєте API.

Налаштування та конфігурація

Щоб увімкнути webhooks, відкрийте сторінку Webhooks на платформі для розробників і натисніть кнопку "Create Webhook". Вкажіть бажану https URL-адресу для отримання webhooks та увімкніть webhook, щоб автоматично отримувати оновлення задач від Meshy. Ви можете мати максимум 5 активних webhooks на один обліковий запис Meshy. Коли webhook увімкнено, всі оновлення статусу API-задач будуть автоматично надсилатися на URL корисного навантаження. З міркувань безпеки наразі ми дозволяємо надсилати webhooks лише на https URL-адреси. Якщо ви хочете налаштувати локальне тестування, перегляньте наступний розділ.

Вимоги до доставки Webhook

Щоб ваш webhook функціонував нормально та продовжував отримувати події:

Ваш сервер повинен відповідати кодом стану HTTP нижче 400 (наприклад, 200 OK, 202 Accepted).
Будь-яка відповідь з кодом стану >= 400 буде розглядатися як невдала доставка.
Кілька послідовних збоїв можуть:
- Спричинити затримку або порушення порядку надходження оновлень progress
- Автоматично вимкнути ваш webhook після повторних спроб (див. Політику автоматичного вимкнення)

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

Якщо фінальна подія задачі не надійшла приблизно після подвоєння її типового часу, отримайте задачу за допомогою її GET кінцевої точки. Див. Життєвий цикл задачі для ознайомлення з типовим часом та тим, скільки слід чекати.

Переадресація Webhooks для локального тестування

Якщо ви хочете протестувати код свого webhook локально, що зазвичай відбувається за http-адресою, ви можете використовувати URL проксі вебхука для переадресації webhooks на ваш комп'ютер або codespace. Нижче наведені рекомендовані кроки з використанням smee.io, але ви можете використовувати будь-який сервіс на свій розсуд для генерації URL проксі вебхука.

Отримання URL проксі вебхука:

У своєму браузері перейдіть на https://smee.io/
Натисніть "Start a new channel"
Скопіюйте повну URL-адресу під "Webhook Proxy URL". Ви будете використовувати цю URL-адресу в наступних кроках налаштування.

Переадресація webhooks:

Якщо у вас ще не встановлено smee-client, виконайте наступну команду у вашому терміналі.

npm install --global smee-client

Щоб отримувати переадресовані webhooks від smee.io, виконайте наступну команду у вашому терміналі. Замініть WEBHOOK_PROXY_URL на ваш URL проксі вебхука з попереднього кроку.

smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Ви повинні побачити вивід, подібний до цього, де WEBHOOK_PROXY_URL — це ваш URL проксі вебхука:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL

Залиште це працювати, поки ви тестуєте свій webhook. Коли захочете зупинити переадресацію webhooks, натисніть Ctrl+C.
Зверніть увагу, що шлях — /webhook, а порт — 3000. Ці значення можуть стати в пригоді, коли пізніше ви захочете налаштувати власний код для отримання доставок webhook.

Створення webhook:

Тепер ви можете використовувати URL проксі вебхука, щоб створити новий webhook на сторінці Webhooks.

Приклад відповіді

Коли статус задачі змінюється, Meshy надсилає POST-запит з корисним навантаженням webhook на вашу налаштовану URL-адресу. Корисне навантаження містить об'єкт задачі у форматі JSON. Для повного опису всіх властивостей об'єкта задачі та прикладів корисного навантаження дивіться: