Webhooks

Spraw, by Meshy wysyłało żądanie POST do Twojego serwera, gdy zadanie API robi postęp lub kończy się, dzięki czemu nie musisz odpytywać API.

Dlaczego warto używać webhooków

Webhooki wymagają mniej pracy i kosztują mniej niż odpytywanie API o status każdego zadania. Meshy wysyła każdą aktualizację w momencie jej wystąpienia, więc otrzymujesz ją szybciej, a webhooki skalują się lepiej niż odpytywanie. Wysyłasz też mniej żądań, co trzyma Cię dalej od limitów częstotliwości.

Konfiguracja webhooka

Aby dodać webhook, wykonaj następujące kroki:

Otwórz stronę Webhooks w Platformie dla deweloperów i kliknij Create Webhook.
W polu Payload URL wpisz adres URL, który będzie odbierał dostarczenia. Meshy dostarcza wyłącznie przez https://.
Zachowaj kopię Webhook Secret, który wypełnia okno dialogowe. Każde dostarczenie go zawiera, dzięki czemu Twój serwer może sprawdzić, że żądanie pochodzi od Meshy. Dla webhooka, który już posiadasz, kliknij ikonę oka w jego kolumnie Secret, aby go zobaczyć.
Zaznacz Active i kliknij Confirm.

Każde konto może mieć 5 aktywnych webhooków i 10 łącznie. Każdy aktywny webhook otrzymuje aktualizacje statusu wszystkich Twoich zadań API.

Aby przetestować webhook z serwerem na swoim komputerze, zobacz Testowanie na komputerze.

Obsługa dostarczenia

Aby przyjąć dostarczenie, odpowiedz statusem poniżej 400, takim jak 200 lub 202. Meshy czeka na odpowiedź około 25 sekund, więc najpierw zapisz dostarczenie i odpowiedz. Wolniejszą pracę, taką jak pobieranie modelu, wykonaj dopiero potem.

Status 400 lub wyższy, albo brak odpowiedzi, liczy się jako nieudane dostarczenie. Meshy ponawia je z coraz dłuższymi odstępami między próbami, do 4 razy dla aktualizacji IN_PROGRESS i do 9 razy dla statusu końcowego. Jeśli 20 kolejnych aktualizacji nie powiedzie się przy każdej próbie, Meshy może dezaktywować webhook. Aby włączyć go ponownie, edytuj go na stronie Webhooks i zaznacz Active.

Napisz swój kod z myślą o tych przypadkach:

Dostarczenia mogą docierać w innej kolejności. Dostarczenie IN_PROGRESS może dotrzeć po tym ostatecznym, więc nie pozwól, aby zastąpiło ono status końcowy.
Ta sama aktualizacja może dotrzeć więcej niż raz. Obsłuż każdą parę id i status tylko raz.
Każdy, kto zna Twój URL, może wysłać do niego żądanie. Porównaj X-MESHY-API-WEBHOOK-SECRET-KEY ze swoją kopią sekretu i odrzuć żądanie, które się nie zgadza.

Jeśli ostateczne dostarczenie zadania nie nadeszło po upływie mniej więcej dwukrotności typowego czasu zadania, pobierz zadanie z jego punktu końcowego GET. Informacje o typowych czasach i o tym, jak długo czekać, znajdziesz w Cyklu życia zadania.

Testowanie na komputerze

Meshy dostarcza tylko na publiczny adres URL https://, więc nie może dotrzeć bezpośrednio do serwera na Twoim komputerze. Aby przetestować kod na swoim komputerze, przekieruj do niego publiczny URL za pomocą proxy webhooka. Poniższe kroki wykorzystują smee.io, ale każda usługa proxy webhooka działa w ten sam sposób.

Otwórz smee.io i kliknij Start a new channel. Skopiuj adres URL pod Webhook Proxy URL.
Jeśli nie masz jeszcze klienta smee, zainstaluj go:
```
npm install --global smee-client
```
Przekieruj kanał do swojego serwera. Zastąp WEBHOOK_PROXY_URL swoim URL proxy webhooka:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
Wynik wygląda następująco, 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. Aby zatrzymać przekierowywanie, naciśnij Ctrl+C. Twój serwer odbiera dostarczenia na porcie 3000 pod ścieżką /webhook, więc skonfiguruj swój kod, aby tam nasłuchiwał.
Na stronie Webhooks utwórz webhook z URL proxy webhooka jako jego Payload URL.

Ładunek dostarczenia

Meshy wysyła dostarczenie, gdy zadanie ma status IN_PROGRESS, oraz kolejne, gdy zadanie osiąga status końcowy. Zadanie może osiągnąć status końcowy bez dostarczenia IN_PROGRESS.

Każde dostarczenie to żądanie POST do Twojego URL ładunku z następującymi nagłówkami:

Nagłówek	Wartość
`X-MESHY-API-WEBHOOK-SECRET-KEY`	Sekret webhooka
`X-MESHY-API-WEBHOOK-USER-ID`	ID użytkownika Meshy, który jest właścicielem webhooka
`Meshy-Webhook-Version`	`v1`, format treści
`Content-Type`	`application/json`
`User-Agent`	`MeshyAPIWebhook/1.0.0`

Treść JSON to obiekt zadania. Jest to ten sam obiekt, który zwraca punkt końcowy GET zadania, z wyjątkiem progress. Dostarczenie wysyła progress jako jedną z tych wartości:

50, gdy zadanie ma status IN_PROGRESS
100, gdy zadanie zakończy się sukcesem
0, gdy zadanie zakończy się niepowodzeniem lub zostanie anulowane

Pola każdego obiektu zadania wraz z przykładem znajdziesz w następujących sekcjach: