Webhooks

Webhooks ermöglichen es dir, Echtzeit-Updates von Meshy zu erhalten, wenn deine API-Aufgaben abgeschlossen sind oder ihren Status ändern. Nach der Konfiguration sendet Meshy Event-Payloads im json-Format per POST an die von dir 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 Updates zum Aufgabenstatus zu erhalten. Webhooks ermöglichen außerdem nahezu Echtzeit-Updates und skalieren letztendlich besser als API-Abfragen. Dadurch kannst du auch deine Rate Limits besser verwalten, insbesondere wenn du ständig abfragst.

Einrichtung & Konfiguration

Um Webhooks zu aktivieren, navigiere zur Seite mit den API-Einstellungen, wenn du in der Meshy-Webanwendung angemeldet bist. Suche den Abschnitt „Webhooks“ unterhalb deiner API keys und klicke auf die Schaltfläche „Create Webhook“. Gib deine gewünschte https-URL an, über die du Webhooks erhalten möchtest, und aktiviere den Webhook, um automatisch Aufgaben-Updates von Meshy zu erhalten. Du kannst maximal 5 aktive Webhooks pro Meshy-Konto haben. Wenn ein Webhook aktiviert ist, werden alle Status-Updates von API-Aufgaben automatisch an die Payload-URL gesendet. Aus Sicherheitsgründen erlauben wir derzeit nur das Senden von Webhooks an https-URLs. Wenn du lokale Tests konfigurieren möchtest, sieh dir den folgenden Abschnitt an.

Anforderungen an die Webhook-Zustellung

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

  • Dein 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 Fortschritts-Updates verzögert werden oder in falscher Reihenfolge eintreffen
    • Deinen Webhook nach wiederholten Versuchen automatisch deaktivieren (siehe Richtlinie zur automatischen Deaktivierung)

Tipp: Gib immer eine Erfolgsantwort zurück, nachdem du die Webhook-Payload validiert und gespeichert hast, auch wenn die weitere Verarbeitung asynchron erfolgt.

Webhooks für lokale Tests weiterleiten

Wenn du deinen Webhook-Code lokal testen möchtest, der typischerweise unter einer http-Adresse erreichbar ist, kannst du eine Webhook-Proxy-URL verwenden, um Webhooks an deinen Computer oder Codespace weiterzuleiten. Unten findest du empfohlene Schritte mit smee.io, aber du kannst jeden beliebigen Dienst verwenden, um eine Webhook-Proxy-URL zu generieren.

Eine Webhook-Proxy-URL erhalten:

  1. Navigiere in deinem Browser zu https://smee.io/
  2. Klicke auf „Start a new channel“
  3. Kopiere die vollständige URL unter „Webhook Proxy URL“. Du wirst diese URL in den folgenden Einrichtungsschritten verwenden.

Webhooks weiterleiten:

  1. Wenn du smee-client noch nicht installiert hast, führe den folgenden Befehl in deinem Terminal aus.
npm install --global smee-client
  1. Um weitergeleitete Webhooks von smee.io zu empfangen, führe den folgenden Befehl in deinem Terminal aus. Ersetze WEBHOOK_PROXY_URL durch deine zuvor erhaltene Webhook-Proxy-URL.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Du solltest eine Ausgabe sehen, die so aussieht, wobei WEBHOOK_PROXY_URL deine Webhook-Proxy-URL ist:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Lass dies laufen, während du deinen Webhook testest. Wenn du das Weiterleiten von Webhooks stoppen möchtest, gib Ctrl+C ein.
    Beachte, dass der Pfad /webhook ist und der Port 3000. Diese Werte können nützlich sein, wenn du später deinen eigenen Code einrichten möchtest, um Webhook-Zustellungen zu empfangen.

Einen Webhook erstellen:

Du kannst nun die Webhook-Proxy-URL verwenden, um einen neuen Webhook auf der Seite mit den Meshy-API-Einstellungen zu erstellen.

Beispielantwort

Wenn sich ein Aufgabenstatus ändert, sendet Meshy eine Webhook-Payload per POST an deine konfigurierte URL. Die Payload enthält das Aufgabenobjekt im JSON-Format. Eine vollständige Beschreibung aller Eigenschaften des Aufgabenobjekts und Beispiel-Payloads findest du unter: