Webhooks

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

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

Використання 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, навіть якщо подальша обробка відбувається асинхронно.

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

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

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

  1. У своєму браузері перейдіть на https://smee.io/
  2. Натисніть "Start a new channel"
  3. Скопіюйте повну URL-адресу під "Webhook Proxy 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 на сторінці Webhooks.

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

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