Webhooks

Webhooks pozwalają na otrzymywanie aktualizacji w czasie rzeczywistym od 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 podane przez Ciebie adresy URL.

Dlaczego warto tworzyć Webhooks

Korzystanie z webhooków ma wiele zalet, szczególnie w kontekście automatycznego sprawdzania statusów zadań API. Webhooki wymagają mniej wysiłku i kosztów niż ciągłe odpytywanie API w celu uzyskania aktualizacji statusu zadania. Webhooki umożliwiają również aktualizacje niemal w czasie rzeczywistym i ostatecznie lepiej się skalują niż odpytywanie API. Dzięki temu możesz też lepiej zarządzać swoimi limitami zapytań, zwłaszcza jeśli odpytujesz API w sposób ciągły.

Konfiguracja i ustawienia

Aby włączyć webhooki, otwórz stronę Webhooks w Platformie Deweloperskiej i kliknij przycisk „Create Webhook”. Podaj żądany adres URL https, na który mają być wysyłane webhooki, i włącz webhook, aby automatycznie otrzymywać aktualizacje zadań od Meshy. Możesz mieć maksymalnie 5 aktywnych webhooków na jedno 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 webhooków wyłącznie na adresy URL https. Jeśli chcesz skonfigurować testy lokalne, zobacz poniższą sekcję.

Wymagania dotyczące dostarczania webhooków

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 zostanie potraktowana jako nieudane dostarczenie.
Kilka kolejnych niepowodzeń może:
- Spowodować opóźnienie aktualizacji progress lub ich dostarczenie w niewłaściwej kolejności
- Automatycznie wyłączyć Twój webhook po wielokrotnych 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.

Jeśli ostateczne zdarzenie zadania nie nadeszło po upływie mniej więcej dwukrotności typowego czasu, pobierz zadanie za pomocą jego punktu końcowego GET. Zobacz Cykl życia zadania, aby poznać typowe czasy i czas oczekiwania.

Przekazywanie webhooków do lokalnych testów

Jeśli chcesz przetestować kod swojego webhooka lokalnie, co zazwyczaj odbywa się pod adresem http, możesz użyć URL proxy webhooka, aby przekazywać webhooki 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, którą chcesz, do wygenerowania URL proxy webhooka.

Uzyskaj URL proxy webhooka:

W przeglądarce przejdź do https://smee.io/
Kliknij „Start a new channel”
Skopiuj pełny adres URL znajdujący się pod „Webhook Proxy URL”. Użyjesz tego adresu URL w kolejnych krokach konfiguracji.

Przekazywanie webhooków:

Jeśli nie masz jeszcze zainstalowanego smee-client, uruchom poniższe polecenie w terminalu.

npm install --global smee-client

Aby odbierać przekazywane webhooki ze smee.io, uruchom poniższe polecenie w terminalu. Zastąp WEBHOOK_PROXY_URL swoim adresem URL proxy webhooka z poprzedniego kroku.

smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Powinieneś zobaczyć wynik wyglądający tak, 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

Pozostaw to uruchomione podczas testowania swojego webhooka. Gdy chcesz zatrzymać przekazywanie webhooków, wciśnij Ctrl+C.
Zwróć uwagę, że ścieżka to /webhook, a port to 3000. Te wartości mogą się przydać, gdy w przyszłości będziesz chciał skonfigurować własny kod do odbierania dostarczanych webhooków.

Utwórz webhook:

Możesz teraz użyć URL proxy webhooka, aby utworzyć nowy webhook na stronie Webhooks.

Przykładowa odpowiedź

Gdy status zadania ulegnie zmianie, 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ładowe ładunki znajdziesz tutaj: