Webhooks

Webhooks pozwalają na otrzymywanie aktualizacji w czasie rzeczywistym od Meshy, gdy zadania API są zakończone lub zmieniają status. Po skonfigurowaniu, Meshy będzie wysyłać ładunki zdarzeń w formacie json do określonych przez Ciebie URL.

Dlaczego tworzyć Webhooks

Korzystanie z webhooks ma kilka zalet, zwłaszcza w kontekście 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 również umożliwiają aktualizacje niemal w czasie rzeczywistym i ostatecznie lepiej skalują się niż odpytywanie API. To również pozwala lepiej zarządzać limitami szybkości, zwłaszcza jeśli ciągle odpytywasz.

Konfiguracja i ustawienia

Aby włączyć webhooks, przejdź do strony ustawień API po zalogowaniu się do aplikacji webowej Meshy. Znajdź sekcję "Webhooks" poniżej swoich Kluczy API i kliknij przycisk "Utwórz Webhook". Podaj swój preferowany URL https, aby 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 do URL ładunku. Ze względów bezpieczeństwa, obecnie pozwalamy na wysyłanie webhooks tylko do 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ć z kodem statusu HTTP poniżej 400 (np. 200 OK, 202 Accepted).
  • Każda odpowiedź z kodem statusu >= 400 będzie traktowana jako nieudana dostawa.
  • Wielokrotne kolejne niepowodzenia mogą:
    • Powodować opóźnienia w aktualizacjach progressu lub ich przybycie w niewłaściwej kolejności
    • Automatycznie wyłączyć Twój webhook po wielokrotnych próbach (zobacz Politykę Automatycznego Wyłączania)

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

Przekierowywanie Webhooks do testów lokalnych

Jeśli chcesz przetestować swój kod webhooka lokalnie, co zazwyczaj znajduje się pod adresem http, możesz użyć URL proxy webhooka, aby przekierować webhooks do swojego komputera lub przestrzeni kodowej. Poniżej znajdują się zalecane kroki przy użyciu smee.io, ale możesz użyć dowolnej usługi, którą chcesz, aby wygenerować URL proxy webhooka.

Uzyskaj URL proxy webhooka:

  1. W przeglądarce przejdź do https://smee.io/
  2. Kliknij "Start a new channel"
  3. Skopiuj pełny URL pod "Webhook Proxy URL". Użyjesz tego URL w kolejnych krokach konfiguracji.

Przekieruj webhooks:

  1. Jeśli nie masz jeszcze zainstalowanego smee-client, uruchom następujące polecenie w terminalu.
npm install --global smee-client
  1. Aby otrzymywać przekierowane webhooks z smee.io, uruchom następujące polecenie w terminalu. Zamień WEBHOOK_PROXY_URL na swój URL proxy webhooka z wcześniejszego kroku.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Powinieneś zobaczyć wyjście, które wygląda 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
  1. Trzymaj to uruchomione, podczas gdy testujesz swój webhook. Kiedy chcesz przestać przekierowywać webhooks, naciśnij Ctrl+C.
    Zauważ, że ścieżka to /webhook, a port to 3000. Te wartości mogą być przydatne, gdy będziesz chciał skonfigurować swój własny kod do odbierania dostaw webhooków później.

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 ładunek webhooka do skonfigurowanego URL. Ładunek zawiera obiekt zadania w formacie JSON. Dla pełnego opisu wszystkich właściwości obiektu zadania i przykładowych ładunków, zobacz: