Webhooks

Mit Webhooks können Sie in Echtzeit Updates von Meshy erhalten, sobald Ihre API-Aufgaben abgeschlossen sind oder ihren 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 kontinuierliche Abfragen der API, um Statusaktualisierungen von Aufgaben zu erhalten. Webhooks ermöglichen außerdem nahezu Echtzeit-Updates und skalieren letztlich besser als API-Polling. Dies ermöglicht Ihnen zudem eine bessere Verwaltung Ihrer Ratenlimits, insbesondere wenn Sie ständig Abfragen durchführen.

Einrichtung & Konfiguration

Um Webhooks zu aktivieren, öffnen Sie die Webhooks-Seite in der Developer Platform 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 Aufgabenaktualisierungen von Meshy zu erhalten. Sie können maximal 5 aktive Webhooks pro Meshy-Konto haben. Wenn ein Webhook aktiviert ist, werden alle API-Aufgabenstatusaktualisierungen 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 Ereignisse 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 Fehlschläge können:
    • dazu führen, dass Fortschrittsaktualisierungen verzögert oder in falscher Reihenfolge eintreffen
    • Ihren Webhook nach wiederholten Versuchen automatisch deaktivieren (siehe Richtlinie zur automatischen Deaktivierung)

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

Webhooks für lokale Tests weiterleiten

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

Webhook-Proxy-URL abrufen:

  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“. Sie verwenden diese URL 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 lautet. Diese Werte können später nützlich sein, wenn Sie Ihren eigenen Code zum Empfangen von Webhook-Zustellungen einrichten möchten.

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 per POST einen Webhook-Payload an Ihre konfigurierte URL. Der Payload enthält das Aufgabenobjekt im JSON-Format. Eine vollständige Beschreibung aller Eigenschaften des Aufgabenobjekts sowie Beispiel-Payloads finden Sie hier: