Webhooks
Lassen Sie Meshy eine POST-Anfrage an Ihren Server senden, wenn ein API-Task Fortschritte macht oder abgeschlossen wird, sodass Sie nicht abfragen (pollen) müssen.
Warum Webhooks verwenden
Webhooks erfordern weniger Aufwand und kosten weniger als das Abfragen des API-Status für jeden Task. Meshy sendet jede Aktualisierung, sobald sie eintritt, sodass Sie sie 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 liefert nur über
https://aus. - Bewahren Sie eine Kopie des Webhook Secret auf, das der Dialog ausfüllt. Jede Zustellung enthält es, sodass Ihr Server prüfen kann, ob eine Anfrage von Meshy stammt. Für einen bereits vorhandenen Webhook klicken Sie auf das Augen-Symbol in der Spalte Secret, um es anzuzeigen.
- Wählen Sie Active aus und klicken Sie auf Confirm.
Jedes Konto kann 5 aktive Webhooks haben, und insgesamt 10. Jeder aktive Webhook empfängt die Statusaktualisierungen all Ihrer API-Tasks.
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 dann. Erledigen Sie die langsamere Arbeit danach, etwa das Herunterladen des Modells.
Ein Status von 400 oder darüber, oder keine Antwort, zählt als fehlgeschlagene Zustellung. Meshy wiederholt sie mit zunehmend längeren Wartezeiten zwischen den Versuchen, bis zu 4 Mal für eine IN_PROGRESS-Aktualisierung und bis zu 9 Mal für einen finalen Status. Schlagen 20 Aktualisierungen in Folge bei jedem Versuch fehl, 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 diese Fälle:
- Zustellungen können in falscher Reihenfolge eintreffen. Eine
IN_PROGRESS-Zustellung kann nach der finalen eintreffen, lassen Sie sie daher nicht den finalen Status ersetzen. - Dieselbe Aktualisierung kann mehr als einmal eintreffen. Verarbeiten Sie jedes Paar aus
idundstatusnur einmal. - Jeder, der Ihre URL kennt, kann eine Anfrage daran senden. Vergleichen Sie
X-MESHY-API-WEBHOOK-SECRET-KEYmit Ihrer Kopie des Secrets und weisen Sie eine Anfrage zurück, die nicht übereinstimmt.
Ist die finale Zustellung eines Tasks nach etwa der doppelten typischen Bearbeitungszeit des Tasks noch nicht eingetroffen, rufen Sie den Task über dessen GET-Endpunkt ab. Typische Zeiten und wie lange Sie warten sollten, finden Sie unter Task-Lebenszyklus.
Auf dem eigenen Computer testen
Meshy liefert nur an eine öffentliche https://-URL aus, kann also 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_URLdurch Ihre Webhook-Proxy-URL:smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000Die Ausgabe sieht wie folgt aus, wobei
WEBHOOK_PROXY_URLIhre Webhook-Proxy-URL ist:Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook Connected WEBHOOK_PROXY_URLLassen 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
3000unter 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 ein Task IN_PROGRESS ist, und eine weitere, wenn der Task einen finalen Status erreicht. Ein Task kann seinen finalen Status auch ohne eine IN_PROGRESS-Zustellung erreichen.
Jede Zustellung ist ein POST an Ihre Payload-URL mit diesen Headern:
| Header | Wert |
|---|---|
X-MESHY-API-WEBHOOK-SECRET-KEY | Das Secret des Webhooks |
X-MESHY-API-WEBHOOK-USER-ID | Die ID des Meshy-Nutzers, dem der Webhook gehört |
Meshy-Webhook-Version | v1, das Format des Bodys |
Content-Type | application/json |
User-Agent | MeshyAPIWebhook/1.0.0 |
Der JSON-Body ist das Task-Objekt. Es ist dasselbe Objekt, das der GET-Endpunkt des Tasks zurückgibt, mit Ausnahme von progress. Eine Zustellung sendet progress als einen dieser Werte:
50, während der TaskIN_PROGRESSist100, wenn der Task erfolgreich ist0, wenn der Task fehlschlägt oder abgebrochen wird
Die Felder jedes Task-Objekts finden Sie mit einem Beispiel in den folgenden Abschnitten: