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ć ładunki zdarzeń w formacie json metodą POST na podane przez Ciebie adresy URL.

Dlaczego warto tworzyć Webhooks

Korzystanie z webhooków niesie ze sobą 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 skalują się lepiej niż odpytywanie API. Pozwala to również lepiej zarządzać 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 Developer Platform i kliknij przycisk „Create Webhook”. Podaj docelowy adres URL https, na który mają być wysyłane webhooki, oraz 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, zapoznaj się z poniższą sekcją.

Wymagania dotyczące dostarczania webhooków

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

  • Twój serwer musi odpowiadać kodem statusu HTTP poniżej 400 (np. 200 OK, 202 Accepted).
  • Każda odpowiedź z kodem statusu >= 400 zostanie potraktowana jako nieudane dostarczenie.
  • Wielokrotne, następujące po sobie niepowodzenia mogą:
    • Powodować opóźnienia lub nieprawidłową kolejność aktualizacji progressu
    • Automatycznie wyłączyć Twój webhook po wielokrotnych próbach (patrz 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 webhooków do testów lokalnych

Jeśli chcesz przetestować kod swojego webhooka lokalnie, co zazwyczaj oznacza adres http, możesz użyć URL proxy webhooka, aby przekazywać webhooki na swój komputer lub 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ź na stronę https://smee.io/
  2. Kliknij „Start a new channel”
  3. Skopiuj pełny adres URL widoczny pod „Webhook Proxy URL”. Będziesz go używać w kolejnych krokach konfiguracji.

Przekazywanie webhooków:

  1. Jeśli nie masz jeszcze zainstalowanego smee-client, uruchom poniższe polecenie w terminalu.
npm install --global smee-client
  1. Aby otrzymywać przekazywane webhooki z smee.io, uruchom poniższe polecenie w terminalu. Zastąp WEBHOOK_PROXY_URL swoim URL proxy webhooka uzyskanym wcześniej.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Powinieneś zobaczyć wynik podobny do poniższego, 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 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 zechcesz w przyszłości 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 URL. Ładunek zawiera obiekt zadania w formacie JSON. Aby uzyskać pełny opis wszystkich właściwości obiektu zadania oraz przykładowe ładunki, zobacz: