Webhooks

Webhooks ermöglichen es Ihnen, asynchrone Benachrichtigungen zu erhalten, wenn ein generativer Prozess abgeschlossen ist. Anstatt den /api/v1/status/{id}-Endpunkt manuell abzufragen, um nach Updates zu suchen, sendet unser System die endgültige Nutzlast direkt an Ihren Server, sobald der Auftrag abgeschlossen ist.

Webhooks verwenden

Um Webhooks mit unserer API zu verwenden, fügen Sie einfach den Parameter webhook_url zu Ihrer /run-Anfrage hinzu:

Wenn der generative Prozess abgeschlossen ist (entweder erfolgreich oder wenn ein Laufzeitfehler auftritt), sendet unser Dispatcher eine POST-Anfrage an Ihre angegebene Webhook-URL, die die vollständige Status-Nutzlast enthält.

Beispiel: Webhooks mit dem /run-Endpunkt verwenden

fetch("https://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
      // ... other inputs
    }
  }),
});

Webhook-Nutzlasten

Die an Ihre Webhook-URL gelieferte Nutzlast ist identisch mit der Nutzlast, die vom /v1/status/{id}-Endpunkt zurückgegeben wird. Sie enthält den Endstatus des Auftrags.

Erfolgs-Nutzlast

Wenn der Prozess erfolgreich abgeschlossen wird, erhält Ihre Webhook-URL eine POST-Anfrage mit dem status auf "success" gesetzt und den Ergebnissen im output-Array:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "success",
  "output": [
    "https://cdn.fititon.app/users/123/results/output_0.png"
  ],
  "error": null,
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:31:15.000Z"
}

Fehler-Nutzlast

Wenn der Prozess aufgrund eines Laufzeitfehlers fehlschlägt (z. B. nicht erkennbares Kleidungsstück, strenge Moderationsfilter), erhält Ihre Webhook-URL die genaue Fehlerzeichenfolge.

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "failed",
  "output": null,
  "error": {
    "name": "InputValidationError",
    "message": "The provided garment image could not be processed due to poor lighting."
  },
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:30:12.000Z"
}

Webhook-Sicherheit

Um sicherzustellen, dass die von Ihnen empfangenen Webhooks tatsächlich von Fit It On stammen und nicht von einer böswilligen dritten Partei gefälscht wurden, sollten Sie einen Verifizierungsmechanismus implementieren.

Der einfachste Weg, Ihre Webhooks zu sichern, besteht darin, einen geheimen Token an die webhook_url anzuhängen, die Sie in Ihrer /v1/run-Anfrage angeben.

Beispiel: Verwendung eines geheimen Tokens

Wenn Sie einen generativen Prozess starten, hängen Sie eine hochzufällige Zeichenfolge an Ihre URL-Abfrageparameter an:

// Make sure to URL-encode the webhook URL if it contains query parameters!
const myWebhookUrl = encodeURIComponent("https://your-server.com/webhook?token=a8f9c2d1e5b47...");

fetch(`https://fititon.app/api/v1/run?webhook_url=${myWebhookUrl}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  // ...
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
    }
  }),
});

Wenn Ihr Server die Webhook-POST-Anfrage empfängt, überprüfen Sie einfach, ob der token-Abfrageparameter mit Ihrer geheimen Zeichenfolge übereinstimmt, bevor Sie die JSON-Nutzlast verarbeiten.

Garantierte Zustellung & Wiederholungsversuche

Unser System implementiert einen unternehmensgerechten Wiederholungsmechanismus, um sicherzustellen, dass Sie keine Webhook-Zustellung verpassen, selbst wenn Ihr Server vorübergehend ausfällt.

• Timeout: Unser Dispatcher erzwingt ein striktes 15-Sekunden-Timeout. Ihr Server muss den Webhook innerhalb von 15 Sekunden mit einem 2xx HTTP-Statuscode bestätigen. Wenn Sie eine aufwendige Verarbeitung durchführen müssen (z. B. das Herunterladen des Bildes), sollten Sie zuerst auf den Webhook antworten und die Daten asynchron verarbeiten.
• Fehler: Wenn Ihr Server einen Nicht-2xx-Statuscode zurückgibt (z. B. 500 Internal Server Error) oder innerhalb von 15 Sekunden nicht antwortet, betrachten wir die Zustellung als fehlgeschlagen.
• Exponentieller Backoff: Das System versucht bis zu 5 Wiederholungen unter Verwendung eines exponentiellen Backoffs (z. B. Wiederholung in 5 Minuten, 15 Minuten, 45 Minuten usw.).

Wenn Sie wissen müssen, welcher Wiederholungsversuch Ihren Server gerade erreicht, können Sie den x-fititon-retry-count-Header in jeder Webhook-Anfrage überprüfen.

Best Practices

1. Idempotenz implementieren: Aufgrund von Netzwerkbedingungen und unserem Wiederholungsmechanismus ist es technisch möglich, dass Ihr Server denselben Webhook mehr als einmal empfängt. Sie sollten das id-Feld verwenden, um zu überprüfen, ob Sie das Ereignis bereits verarbeitet haben.
2. Schnell antworten: Geben Sie immer sofort einen 200 OK-Status zurück, bevor Sie Bilder herunterladen oder Datenbanken aktualisieren.
3. Webhooks immer verifizieren: Erwägen Sie die Implementierung eines Verifizierungsmechanismus (wie den oben erwähnten geheimen URL-Token), um sicherzustellen, dass Webhooks von unserem Dienst stammen und böswillige Akteure daran zu hindern, Nutzlasten zu fälschen.