lowpoly буде вимкнено 30 жовт. 2026 р.. Перейдіть на іншу модель до цих дат, щоб уникнути помилок у запитах. Усі застарілі функції

Webhooks

Нехай Meshy надсилає запит POST на ваш сервер, коли завдання API робить прогрес або завершується, тож вам не потрібно опитувати (polling).

Навіщо використовувати webhooks

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

Налаштування webhook

Щоб додати webhook, виконайте ці кроки:

  1. Відкрийте сторінку Webhooks на Платформі розробника і натисніть Create Webhook.
  2. У полі Payload URL введіть URL, який отримуватиме доставки. Meshy здійснює доставку лише через https://.
  3. Збережіть копію Webhook Secret, яку діалог заповнює автоматично. Кожна доставка містить його, тож ваш сервер може перевірити, що запит прийшов від Meshy. Для webhook, який у вас уже є, натисніть іконку ока в стовпці Secret, щоб його побачити.
  4. Виберіть Active і натисніть Confirm.

Кожен обліковий запис може мати 5 активних webhooks і 10 загалом. Кожен активний webhook отримує оновлення статусу всіх ваших завдань API.

Щоб протестувати webhook із сервером на вашому комп'ютері, див. Тестування на вашому комп'ютері.

Обробка доставки

Щоб прийняти доставку, відповідайте статусом нижче 400, наприклад 200 або 202. Meshy чекає відповіді близько 25 секунд, тож спочатку збережіть доставку, а потім відповідайте. Виконуйте повільну роботу вже після цього, наприклад завантаження моделі.

Статус 400 або вище, або відсутність відповіді, вважається невдалою доставкою. Meshy повторює спроби з довшими інтервалами очікування, до 4 разів для оновлення IN_PROGRESS і до 9 разів для фінального статусу. Якщо 20 оновлень поспіль не вдаються при кожній спробі, Meshy може деактивувати webhook. Щоб увімкнути його знову, відредагуйте його на сторінці Webhooks і виберіть Active.

Пишіть код з урахуванням цих випадків:

  • Доставки можуть прибувати не по порядку. Доставка IN_PROGRESS може прибути після фінальної, тож не дозволяйте їй замінювати фінальний статус.
  • Те саме оновлення може прибути більше одного разу. Обробляйте кожну пару id та status один раз.
  • Будь-хто, хто знає ваш URL, може надіслати на нього запит. Порівняйте X-MESHY-API-WEBHOOK-SECRET-KEY із вашою копією секрету й відхиляйте запит, який не збігається.

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

Тестування на вашому комп'ютері

Meshy здійснює доставку лише на публічний URL https://, тож він не може напряму дістатися сервера на вашому комп'ютері. Щоб протестувати код на вашому комп'ютері, перенаправте публічний URL до нього за допомогою проксі вебхука. Ці кроки використовують smee.io, і будь-яка служба проксі вебхука працює так само.

  1. Відкрийте smee.io і натисніть Start a new channel. Скопіюйте URL під Webhook Proxy URL.

  2. Якщо у вас ще немає клієнта smee, встановіть його:

    npm install --global smee-client

  3. Перенаправте канал на ваш сервер. Замініть 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

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

  4. На сторінці Webhooks створіть webhook із URL проксі вебхука як вашим Payload URL.

Корисне навантаження доставки

Meshy надсилає доставку, поки завдання має статус IN_PROGRESS, і ще одну, коли завдання досягає фінального статусу. Завдання може досягти фінального статусу без доставки IN_PROGRESS.

Кожна доставка — це запит POST на ваш Payload URL із такими заголовками:

ЗаголовокЗначення
X-MESHY-API-WEBHOOK-SECRET-KEYСекрет webhook
X-MESHY-API-WEBHOOK-USER-IDID користувача Meshy, якому належить webhook
Meshy-Webhook-Versionv1, формат тіла
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

Тіло у форматі JSON — це об'єкт завдання. Це той самий об'єкт, який повертає кінцева точка GET завдання, за винятком progress. Доставка надсилає progress як одне з таких значень:

  • 50, поки завдання має статус IN_PROGRESS
  • 100, коли завдання успішно завершується
  • 0, коли завдання не вдається або скасовується

Поля кожного об'єкта завдання з прикладом дивіться в наступних розділах: