Webhooks

Webhooks umożliwiają otrzymywanie aktualizacji w czasie rzeczywistym z Meshy, gdy Twoje zadania API zostaną ukończone lub zmienią status. Po skonfigurowaniu Meshy będzie wysyłać metodą POST ładunki zdarzeń w formacie json na wskazane przez Ciebie adresy URL.

Dlaczego tworzyć Webhooks

Korzystanie z Webhooks ma kilka zalet, szczególnie w zakresie automatycznego sprawdzania statusów zadań API. Webhooks wymagają mniej wysiłku i kosztów niż ciągłe odpytywanie API w celu uzyskania aktualizacji statusu zadań. Webhooks umożliwiają też aktualizacje niemal w czasie rzeczywistym i ostatecznie skalują się lepiej niż odpytywanie API. Pozwala to również lepiej zarządzać limitami szybkości, zwłaszcza jeśli stale odpytujesz API.

Ustawienia i konfiguracja

Aby włączyć Webhooks, przejdź do strony ustawień API po zalogowaniu się do aplikacji webowej Meshy. Znajdź sekcję "Webhooks" poniżej swoich API Keys i kliknij przycisk "Utwórz Webhook". Podaj wybrany adres URL https, z którego chcesz otrzymywać Webhooks, i włącz webhook, aby automatycznie otrzymywać aktualizacje zadań z Meshy. Możesz mieć maksymalnie 5 aktywnych Webhooks na konto Meshy. Gdy webhook jest włączony, wszystkie aktualizacje statusu zadań API będą automatycznie wysyłane na URL ładunku. Ze względów bezpieczeństwa obecnie zezwalamy na wysyłanie Webhooks tylko na adresy URL https. Jeśli chcesz skonfigurować testowanie lokalne, zobacz następną sekcję.

Wymagania dotyczące dostarczania Webhook

Aby Twój webhook działał normalnie i nadal otrzymywał zdarzenia:

  • Twój serwer musi odpowiedzieć kodem statusu HTTP poniżej 400 (np. 200 OK, 202 Accepted).
  • Każda odpowiedź z kodem statusu >= 400 będzie traktowana jako nieudane dostarczenie.
  • Wiele kolejnych niepowodzeń może:
    • Spowodować opóźnienie aktualizacji progress lub ich nadejście w nieprawidłowej kolejności
    • Automatycznie wyłączyć Twój webhook po ponawianych próbach (zobacz Zasady automatycznego wyłączania)

Wskazówka: Zawsze zwracaj odpowiedź sukcesu po zweryfikowaniu i zapisaniu ładunku webhooka, nawet jeśli dalsze przetwarzanie odbywa się asynchronicznie.

Przekazywanie Webhooks do testowania lokalnego

Jeśli chcesz testować swój kod webhooka lokalnie, co zazwyczaj odbywa się pod adresem http, możesz użyć URL proxy webhooka, aby przekazywać Webhooks na swój komputer lub do codespace. Poniżej znajdują się zalecane kroki z użyciem smee.io, ale możesz użyć dowolnej usługi, aby wygenerować URL proxy webhooka.

Uzyskaj URL proxy webhooka:

  1. W przeglądarce przejdź do https://smee.io/
  2. Kliknij "Rozpocznij nowy kanał"
  3. Skopiuj pełny adres URL pod "URL proxy webhooka". Użyjesz tego adresu URL w kolejnych krokach konfiguracji.

Przekazuj Webhooks:

  1. Jeśli nie masz jeszcze zainstalowanego smee-client, uruchom następujące polecenie w terminalu.
npm install --global smee-client
  1. Aby odbierać przekazywane Webhooks z smee.io, uruchom następujące polecenie w terminalu. Zastąp WEBHOOK_PROXY_URL swoim wcześniejszym URL proxy webhooka.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Powinien pojawić się wynik podobny do tego, gdzie WEBHOOK_PROXY_URL to Twój URL proxy webhooka:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Pozostaw to uruchomione podczas testowania swojego webhooka. Gdy chcesz zatrzymać przekazywanie Webhooks, wprowadź Ctrl+C.
    Zwróć uwagę, że ścieżka to /webhook, a port to 3000. Te wartości mogą się przydać, gdy później zechcesz skonfigurować własny kod do odbierania dostarczeń webhooka.

Utwórz webhook:

Możesz teraz użyć URL proxy webhooka, aby utworzyć nowy webhook na stronie ustawień Meshy API.

Przykładowa odpowiedź

Gdy status zadania się zmienia, Meshy wyśle metodą POST ładunek webhooka na skonfigurowany przez Ciebie adres URL. Ładunek zawiera obiekt zadania w formacie JSON. Pełny opis wszystkich właściwości obiektu zadania oraz przykładowych ładunków znajdziesz tutaj: