Webhooks

Webhooks ermöglichen es Ihnen, Echtzeit-Updates von Meshy zu erhalten, wenn Ihre API-Aufgaben abgeschlossen sind oder den Status ändern. Sobald sie konfiguriert sind, sendet Meshy Ereignis-Payloads im JSON-Format an die von Ihnen angegebenen URLs.

Warum Webhooks erstellen

Die Verwendung von Webhooks bietet mehrere Vorteile, insbesondere im Hinblick auf die automatische Überprüfung von API-Aufgabenstatus. Webhooks erfordern weniger Aufwand und Kosten als das kontinuierliche Abfragen der API, um Statusaktualisierungen zu erhalten. Webhooks ermöglichen auch nahezu Echtzeit-Updates und skalieren letztendlich besser als API-Abfragen. Dies ermöglicht es Ihnen auch, Ihre Ratenlimits besser zu verwalten, insbesondere wenn Sie ständig abfragen.

Einrichtung & Konfiguration

Um Webhooks zu aktivieren, navigieren Sie zur API-Einstellungsseite, wenn Sie in der Meshy-Webanwendung angemeldet sind. Finden Sie den Abschnitt "Webhooks" unter Ihren API-Schlüsseln und klicken Sie auf die Schaltfläche "Webhook erstellen". Geben Sie Ihre gewünschte HTTPS-URL an, um Webhooks zu empfangen, 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, siehe 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 Fehler können:
    • Verzögerungen oder falsche Reihenfolge bei Fortschrittsaktualisierungen verursachen
    • Ihren Webhook nach wiederholten Versuchen automatisch deaktivieren (siehe Auto-Deaktivierungsrichtlinie)

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

Weiterleitung von Webhooks für lokale Tests

Wenn Sie Ihren Webhook-Code lokal testen möchten, der typischerweise unter einer HTTP-Adresse läuft, können Sie eine Webhook-Proxy-URL verwenden, um Webhooks an Ihren Computer oder Codespace weiterzuleiten. Die folgenden Schritte werden mit smee.io empfohlen, aber Sie können jeden 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". Sie werden diese URL in den folgenden Einrichtungsschritten verwenden.

Webhooks weiterleiten:

  1. Wenn 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 so 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 nützlich sein, wenn Sie später Ihren eigenen Code einrichten möchten, um Webhook-Zustellungen zu empfangen.

Einen Webhook erstellen:

Sie können jetzt die Webhook-Proxy-URL verwenden, um einen neuen Webhook auf der Meshy API-Einstellungsseite zu erstellen.

Beispielantwort

Wenn sich der Status einer Aufgabe ändert, sendet Meshy eine Webhook-Payload an Ihre konfigurierte URL. Die Payload enthält das Aufgabenobjekt im JSON-Format. Für eine vollständige Beschreibung aller Aufgabenobjekteigenschaften und Beispiel-Payloads siehe: