Webhooks

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

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

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

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

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

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

Якщо ви хочете протестувати ваш код webhook локально, що зазвичай знаходиться за адресою http, ви можете використовувати URL проксі вебхука для пересилання webhooks на ваш комп'ютер або кодовий простір. Нижче наведені рекомендовані кроки з використанням 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 на сторінці налаштувань Meshy API.

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

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