Webhooks

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

Зачем создавать Webhooks

Использование webhooks имеет несколько преимуществ, особенно в отношении автоматической проверки статусов API-задач. Webhooks требуют меньше усилий и затрат, чем постоянный опрос API для получения обновлений статуса задач. Webhooks также обеспечивают обновления практически в реальном времени и в конечном итоге лучше масштабируются, чем опрос API. Это также позволяет лучше управлять лимитами скорости запросов, особенно если вы выполняете постоянный опрос.

Настройка и конфигурация

Чтобы включить webhooks, откройте страницу Webhooks в Developer Platform и нажмите кнопку "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 на ваш компьютер или 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. Полное описание всех свойств объекта задачи и примеры полезной нагрузки см. здесь: