Webhooks

Настройте отправку Meshy запроса POST на ваш сервер при прогрессе или завершении задачи API, чтобы вам не нужно было опрашивать API.

Зачем использовать webhooks

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

Настройка webhook

Чтобы добавить webhook, выполните следующие шаги:

Откройте страницу Webhooks в Developer Platform и нажмите Create Webhook.
В поле Payload URL введите URL, который будет получать доставки. Meshy доставляет только по https://.
Сохраните копию Webhook Secret, который диалоговое окно заполнит автоматически. Каждая доставка содержит его, поэтому ваш сервер может проверить, что запрос пришёл от Meshy. Для уже существующего webhook нажмите на значок глаза в столбце Secret, чтобы его увидеть.
Выберите 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 с помощью прокси webhook. В этих шагах используется smee.io, и любой сервис прокси webhook работает аналогичным образом.

Откройте smee.io и нажмите Start a new channel. Скопируйте URL под Webhook Proxy URL.
Если у вас ещё нет клиента smee, установите его:
```
npm install --global smee-client
```
Перенаправьте канал на ваш сервер. Замените 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, поэтому настройте ваш код на прослушивание именно там.
На странице Webhooks создайте webhook, указав URL прокси вебхука в качестве его Payload URL.

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

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

Каждая доставка представляет собой запрос POST на ваш URL полезной нагрузки со следующими заголовками:

Заголовок	Значение
`X-MESHY-API-WEBHOOK-SECRET-KEY`	Секрет webhook
`X-MESHY-API-WEBHOOK-USER-ID`	ID пользователя Meshy, владеющего webhook
`Meshy-Webhook-Version`	`v1`, формат тела
`Content-Type`	`application/json`
`User-Agent`	`MeshyAPIWebhook/1.0.0`

Тело JSON представляет собой объект задачи. Это тот же объект, который возвращает GET эндпоинт задачи, за исключением progress. Доставка отправляет progress как одно из следующих значений:

50, пока задача в статусе IN_PROGRESS
100, когда задача завершается успешно
0, когда задача завершается неудачно или отменяется

Поля каждого объекта задачи с примером см. в следующих разделах: