Webhooks

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

Навіщо створювати Webhooks

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

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

Щоб увімкнути Webhooks, перейдіть на сторінку налаштувань API, увійшовши до вебзастосунку Meshy. Знайдіть розділ "Webhooks" нижче ваших API Keys і натисніть кнопку "Створити 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, навіть якщо подальша обробка відбувається асинхронно.

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

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

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

  1. У браузері перейдіть на https://smee.io/
  2. Натисніть "Почати новий канал"
  3. Скопіюйте повний URL під "URL проксі вебхука". Ви використовуватимете цей URL у наступних кроках налаштування.

Перенаправте Webhooks:

  1. Якщо у вас ще не встановлено smee-client, виконайте таку команду в терміналі.
npm install --global smee-client
  1. Щоб отримувати перенаправлені 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
  1. Залиште цей процес запущеним, поки тестуєте свій webhook. Коли захочете зупинити перенаправлення Webhooks, натисніть Ctrl+C.
    Зверніть увагу, що шлях — /webhook, а порт — 3000. Ці значення можуть стати в пригоді, коли ви захочете згодом налаштувати власний код для отримання доставок webhook.

Створіть webhook:

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

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

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