lowpoly wird am 30.10.2026 abgeschaltet. Wechseln Sie vor diesen Terminen das Modell, um Fehler bei Anfragen zu vermeiden.

Webhooks

Mit Webhooks können Sie Echtzeit-Updates von Meshy erhalten, wenn Ihre API-Aufgaben abgeschlossen sind oder den Status ändern. Nach der Konfiguration sendet Meshy Event-Payloads im JSON-Format per POST an die von Ihnen angegebenen URLs.

Warum Webhooks erstellen

Die Verwendung von Webhooks bietet mehrere Vorteile, insbesondere im Hinblick auf die automatische Überprüfung des API-Aufgabenstatus. Webhooks erfordern weniger Aufwand und Kosten als das ständige Abfragen der API, um Statusaktualisierungen von Aufgaben zu erhalten. Webhooks ermöglichen außerdem nahezu Echtzeit-Updates und lassen sich letztlich besser skalieren als API-Polling. Dies ermöglicht Ihnen zudem eine bessere Verwaltung Ihrer Ratenlimits, insbesondere wenn Sie kontinuierlich abfragen.

Einrichtung & Konfiguration

Um Webhooks zu aktivieren, öffnen Sie die Webhooks-Seite in der Entwicklerplattform und klicken Sie auf die Schaltfläche „Create Webhook“. Geben Sie die gewünschte https-URL an, unter der Sie Webhooks empfangen möchten, und aktivieren Sie den Webhook, um automatisch Aufgaben-Updates von Meshy zu erhalten. Sie können maximal 5 aktive Webhooks pro Meshy-Konto haben. Wenn ein Webhook aktiviert ist, werden alle API-Aufgabenstatus-Updates automatisch an die Payload-URL gesendet. Aus Sicherheitsgründen erlauben wir derzeit nur das Senden von Webhooks an https-URLs. Wenn Sie lokale Tests konfigurieren möchten, lesen Sie den folgenden Abschnitt.

Anforderungen an die Webhook-Zustellung

Damit Ihr Webhook normal funktioniert und weiterhin Events empfängt:

  • Ihr Server muss mit einem HTTP-Statuscode unter 400 antworten (z. B. 200 OK, 202 Accepted).
  • Jede Antwort mit einem Statuscode >= 400 wird als fehlgeschlagene Zustellung behandelt.
  • Mehrere aufeinanderfolgende Fehler können:
    • dazu führen, dass Progress-Updates verzögert oder in falscher Reihenfolge eintreffen
    • Ihren Webhook nach wiederholten Versuchen automatisch deaktivieren (siehe Richtlinie zur automatischen Deaktivierung)

Tipp: Senden Sie immer eine Erfolgsantwort zurück, nachdem Sie den Webhook-Payload validiert und gespeichert haben, auch wenn die weitere Verarbeitung asynchron erfolgt.

Falls das finale Event einer Aufgabe nach etwa der doppelten üblichen Zeit noch nicht eingetroffen ist, rufen Sie die Aufgabe über ihren GET-Endpunkt ab. Siehe Aufgabenlebenszyklus für typische Zeiten und wie lange Sie warten sollten.

Webhooks für lokale Tests weiterleiten

Wenn Sie Ihren Webhook-Code lokal testen möchten, der typischerweise unter einer http-Adresse liegt, können Sie eine Webhook-Proxy-URL verwenden, um Webhooks an Ihren Computer oder Codespace weiterzuleiten. Im Folgenden finden Sie empfohlene Schritte unter Verwendung von smee.io, Sie können jedoch jeden beliebigen Dienst verwenden, um eine Webhook-Proxy-URL zu generieren.

Eine Webhook-Proxy-URL erhalten:

  1. Navigieren Sie in Ihrem Browser zu https://smee.io/
  2. Klicken Sie auf „Start a new channel“
  3. Kopieren Sie die vollständige URL unter „Webhook Proxy URL“. Diese URL verwenden Sie in den folgenden Einrichtungsschritten.

Webhooks weiterleiten:

  1. Falls Sie smee-client noch nicht installiert haben, führen Sie den folgenden Befehl in Ihrem Terminal aus.
npm install --global smee-client
  1. Um weitergeleitete Webhooks von smee.io zu empfangen, führen Sie den folgenden Befehl in Ihrem Terminal aus. Ersetzen Sie WEBHOOK_PROXY_URL durch Ihre zuvor erhaltene Webhook-Proxy-URL.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Sie sollten eine Ausgabe sehen, die wie folgt aussieht, 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
  1. Lassen Sie dies laufen, während Sie Ihren Webhook testen. Wenn Sie die Weiterleitung von Webhooks stoppen möchten, drücken Sie Strg+C.
    Beachten Sie, dass der Pfad /webhook und der Port 3000 ist. Diese Werte können hilfreich sein, wenn Sie später Ihren eigenen Code zum Empfang von Webhook-Zustellungen einrichten möchten.

Einen Webhook erstellen:

Sie können nun die Webhook-Proxy-URL verwenden, um auf der Webhooks-Seite einen neuen Webhook zu erstellen.

Beispielantwort

Wenn sich der Status einer Aufgabe ändert, sendet Meshy einen Webhook-Payload per POST an Ihre konfigurierte URL. Der Payload enthält das Aufgabenobjekt im JSON-Format. Eine vollständige Beschreibung aller Eigenschaften des Aufgabenobjekts und Beispiel-Payloads finden Sie hier: