Webhooks

Met webhooks kunt u asynchrone meldingen ontvangen wanneer een generatief proces is voltooid. In plaats van handmatig de /api/v1/status/{id} endpoint te pollen om te controleren op updates, stuurt ons systeem de uiteindelijke payload direct naar uw server zodra de taak is voltooid.

Hoe Webhooks te Gebruiken

Om webhooks met onze API te gebruiken, voegt u eenvoudig de webhook_url parameter toe aan uw /run verzoek:

Wanneer het generatieve proces is voltooid (succesvol of als er een runtimefout optreedt), stuurt onze dispatcher een POST verzoek naar uw opgegeven webhook-URL met de complete statuspayload.

Voorbeeld: Webhooks Gebruiken met de /run Endpoint

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 Payloads

De payload die naar uw webhook-URL wordt gestuurd, is identiek aan de payload die wordt geretourneerd door de /v1/status/{id} endpoint. Deze bevat de uiteindelijke status van de taak.

Succes Payload

Wanneer het proces succesvol is voltooid, ontvangt uw webhook-URL een POST verzoek met de status ingesteld op "success" en de resultaten in de 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"
}

Fout Payload

Als het proces mislukt als gevolg van een runtimefout (bijv. onherkenbaar kledingstuk, strikte moderatiefilters), ontvangt uw webhook-URL de exacte foutmelding.

{
  "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 Beveiliging

Om ervoor te zorgen dat de webhooks die u ontvangt daadwerkelijk afkomstig zijn van Fit It On en niet zijn vervalst door een kwaadwillende derde partij, dient u een verificatiemechanisme te implementeren.

De eenvoudigste manier om uw webhooks te beveiligen, is door een geheim token toe te voegen aan de webhook_url die u opgeeft in uw /v1/run verzoek.

Voorbeeld: Een Geheim Token Gebruiken

Wanneer u een generatief proces start, voegt u een zeer willekeurige string toe aan uw URL-queryparameters:

// Zorg ervoor dat de webhook-URL URL-gecodeerd is als deze queryparameters bevat!
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",
    }
  }),
});

Wanneer uw server het webhook POST verzoek ontvangt, controleert u eenvoudigweg of de token queryparameter overeenkomt met uw geheime string voordat u de JSON-payload verwerkt.

Gegarandeerde Levering & Herpogingen

Ons systeem implementeert een enterprise-grade herpogingsmechanisme om ervoor te zorgen dat u nooit een webhook-levering mist, zelfs als uw server tijdelijk offline is.

• Timeout: Onze dispatcher hanteert een strikte 15-seconden timeout. Uw server moet de webhook binnen 15 seconden bevestigen met een 2xx HTTP-statuscode. Als u zware verwerkingen moet uitvoeren (zoals het downloaden van de afbeelding), moet u eerst op de webhook reageren en de gegevens asynchroon verwerken.
• Fouten: Als uw server een niet-2xx statuscode retourneert (bijv. 500 Internal Server Error), of niet binnen 15 seconden reageert, beschouwen wij de levering als mislukt.
• Exponentiële Backoff: Het systeem zal tot 5 herpogingen doen met behulp van exponentiële backoff (bijv. opnieuw proberen na 5 minuten, 15 minuten, 45 minuten, enz.).

Als u wilt weten welke herpoging momenteel uw server bereikt, kunt u de x-fititon-retry-count header inspecteren die in elk webhook-verzoek is opgenomen.

Best Practices

1. Implementeer Idempotentie: Vanwege netwerkomstandigheden en ons herpogingsmechanisme is het technisch mogelijk dat uw server dezelfde webhook meer dan eens ontvangt. U dient het id veld te gebruiken om te controleren of u de gebeurtenis al hebt verwerkt.
2. Reageer Snel: Retourneer altijd onmiddellijk een 200 OK status voordat u afbeeldingen downloadt of databases bijwerkt.
3. Verifieer Altijd Webhooks: Overweeg een verificatiemechanisme te implementeren (zoals het hierboven genoemde geheime URL-token) om ervoor te zorgen dat webhooks afkomstig zijn van onze service en om te voorkomen dat kwaadwillende actoren payloads vervalsen.