Webhooks

Lassen Sie Meshy eine POST-Anfrage an Ihren Server senden, wenn eine API-Aufgabe Fortschritte macht oder abgeschlossen wird, damit Sie nicht abfragen (pollen) müssen.

Warum Webhooks verwenden

Webhooks erfordern weniger Aufwand und kosten weniger als das Abfragen des API-Status für jede Aufgabe. Meshy sendet jedes Update, sobald es eintritt, sodass Sie es schneller erhalten, und Webhooks skalieren besser als Polling. Außerdem senden Sie weniger Anfragen, wodurch Sie weiter von Ihren Ratenlimits entfernt bleiben.

Einen Webhook einrichten

Um einen Webhook hinzuzufügen, folgen Sie diesen Schritten:

Öffnen Sie die Webhooks-Seite in der Developer Platform und klicken Sie auf Create Webhook.
Geben Sie unter Payload URL die URL ein, die die Zustellungen empfängt. Meshy stellt nur über https:// zu.
Wählen Sie Active aus und klicken Sie auf Confirm.

Jedes Konto kann 5 aktive Webhooks haben, insgesamt 10. Jeder aktive Webhook empfängt die Statusaktualisierungen aller Ihrer API-Aufgaben.

Um einen Webhook mit einem Server auf Ihrem Computer zu testen, siehe Auf dem eigenen Computer testen.

Eine Zustellung verarbeiten

Um eine Zustellung zu akzeptieren, antworten Sie mit einem Status unter 400, etwa 200 oder 202. Meshy wartet etwa 25 Sekunden auf die Antwort. Speichern Sie die Zustellung daher zuerst und antworten Sie erst danach. Erledigen Sie die zeitaufwendige Arbeit, wie das Herunterladen des Modells, im Anschluss.

Ein Status von 400 oder höher, oder keine Antwort, zählt als fehlgeschlagene Zustellung. Meshy wiederholt den Versuch mit zunehmend längeren Wartezeiten zwischen den Versuchen, bis zu 4 Mal für ein IN_PROGRESS-Update und bis zu 9 Mal für einen endgültigen Status. Wenn 20 Updates in Folge bei jedem Versuch fehlschlagen, kann Meshy den Webhook deaktivieren. Um ihn wieder zu aktivieren, bearbeiten Sie ihn auf der Webhooks-Seite und wählen Sie Active aus.

Schreiben Sie Ihren Code für folgende Fälle:

Zustellungen können in der falschen Reihenfolge eintreffen. Eine IN_PROGRESS-Zustellung kann nach der endgültigen eintreffen, lassen Sie sie also nicht einen endgültigen Status ersetzen.
Dasselbe Update kann mehr als einmal eintreffen. Verarbeiten Sie jedes Paar aus id und status nur einmal.

Wenn die endgültige Zustellung einer Aufgabe nach etwa dem Doppelten ihrer üblichen Dauer noch nicht eingetroffen ist, rufen Sie die Aufgabe über ihren GET-Endpunkt ab. Informationen zu typischen Zeiten und Wartedauern finden Sie unter Aufgabenlebenszyklus.

Auf dem eigenen Computer testen

Meshy stellt nur an eine öffentliche https://-URL zu und kann daher einen Server auf Ihrem Computer nicht direkt erreichen. Um Code auf Ihrem Computer zu testen, leiten Sie eine öffentliche URL mit einem Webhook-Proxy an ihn weiter. Diese Schritte verwenden smee.io, und jeder Webhook-Proxy-Dienst funktioniert auf die gleiche Weise.

Öffnen Sie smee.io und klicken Sie auf Start a new channel. Kopieren Sie die URL unter Webhook Proxy URL.
Falls Sie den smee-Client noch nicht haben, installieren Sie ihn:
```
npm install --global smee-client
```
Leiten Sie den Kanal an Ihren Server weiter. Ersetzen Sie WEBHOOK_PROXY_URL durch Ihre Webhook-Proxy-URL:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
Die Ausgabe sieht folgendermaßen aus, wobei WEBHOOK_PROXY_URL Ihre Webhook-Proxy-URL ist:
```
Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
```
Lassen Sie es während des Testens laufen. Um die Weiterleitung zu stoppen, drücken Sie Strg+C. Ihr Server empfängt die Zustellungen auf Port 3000 unter dem Pfad /webhook, richten Sie Ihren Code also so ein, dass er dort lauscht.
Erstellen Sie auf der Webhooks-Seite einen Webhook mit der Webhook-Proxy-URL als Payload URL.

Zustellungs-Payload

Meshy sendet eine Zustellung, während eine Aufgabe IN_PROGRESS ist, und eine weitere, wenn die Aufgabe einen endgültigen Status erreicht. Eine Aufgabe kann ihren endgültigen Status auch ohne eine IN_PROGRESS-Zustellung erreichen.

Jede Zustellung ist eine POST-Anfrage an Ihre Payload-URL mit dem Aufgabenobjekt als JSON-Body. Es ist dasselbe Objekt, das der GET-Endpunkt der Aufgabe zurückgibt, mit Ausnahme von progress. Eine Zustellung sendet progress als einen dieser Werte:

50, während die Aufgabe IN_PROGRESS ist
100, wenn die Aufgabe erfolgreich ist
0, wenn die Aufgabe fehlschlägt oder abgebrochen wird

Die Felder der einzelnen Aufgabenobjekte mit jeweils einem Beispiel finden Sie in den folgenden Abschnitten: