Webhooks

Les webhooks vous permettent de recevoir des notifications asynchrones lorsqu'un processus génératif est terminé. Au lieu d'interroger manuellement le point de terminaison /api/v1/status/{id} pour vérifier les mises à jour, notre système envoie la charge utile finale directement à votre serveur dès que la tâche est terminée.

Comment utiliser les webhooks

Pour utiliser les webhooks avec notre API, ajoutez simplement le paramètre webhook_url à votre requête /run :

Lorsque le processus génératif est terminé (soit avec succès, soit s'il rencontre une erreur d'exécution), notre répartiteur enverra une requête POST à l'URL de votre webhook spécifiée, contenant la charge utile de statut complète.

Exemple : Utilisation des webhooks avec le point de terminaison /run

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
    }
  }),
});

Charges utiles des webhooks

La charge utile livrée à l'URL de votre webhook est identique à la charge utile renvoyée par le point de terminaison /v1/status/{id}. Elle contient l'état final de la tâche.

Charge utile en cas de succès

Lorsque le processus se termine avec succès, l'URL de votre webhook recevra une requête POST avec le status défini sur "success" et les résultats dans le tableau output :

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

Charge utile en cas d'erreur

Si le processus échoue en raison d'une erreur d'exécution (par exemple, vêtement non reconnaissable, filtres de modération stricts), l'URL de votre webhook recevra la chaîne d'erreur exacte.

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

Sécurité des webhooks

Pour vous assurer que les webhooks que vous recevez proviennent réellement de Fit It On et ne sont pas falsifiés par un tiers malveillant, vous devez implémenter un mécanisme de vérification.

Le moyen le plus simple de sécuriser vos webhooks est d'ajouter un jeton secret à la webhook_url que vous fournissez dans votre requête /v1/run.

Exemple : Utilisation d'un jeton secret

Lorsque vous démarrez un processus génératif, ajoutez une chaîne très aléatoire à vos paramètres de requête URL :

// Assurez-vous d'encoder l'URL du webhook si elle contient des paramètres de requête !
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",
    }
  }),
});

Lorsque votre serveur reçoit la requête POST du webhook, vérifiez simplement que le paramètre de requête token correspond à votre chaîne secrète avant de traiter la charge utile JSON.

Livraison garantie et tentatives de réessai

Notre système implémente un mécanisme de réessai de niveau entreprise pour vous assurer de ne jamais manquer une livraison de webhook, même si votre serveur subit une interruption temporaire.

• Délai d'attente : Notre répartiteur applique un délai d'attente strict de 15 secondes. Votre serveur doit accuser réception du webhook avec un code de statut HTTP 2xx dans les 15 secondes. Si vous devez effectuer un traitement lourd (comme le téléchargement de l'image), vous devez répondre au webhook en premier, puis traiter les données de manière asynchrone.
• Échecs : Si votre serveur renvoie un code de statut non-2xx (par exemple, 500 Internal Server Error), ou ne répond pas dans les 15 secondes, nous considérons la livraison comme échouée.
• Backoff exponentiel : Le système tentera jusqu'à 5 réessais en utilisant un backoff exponentiel (par exemple, réessai dans 5 minutes, 15 minutes, 45 minutes, etc.).

Si vous avez besoin de savoir quelle tentative de réessai atteint actuellement votre serveur, vous pouvez inspecter l'en-tête x-fititon-retry-count inclus dans chaque requête webhook.

Bonnes pratiques

1. Implémentez l'idempotence : En raison des conditions réseau et de notre mécanisme de réessai, il est techniquement possible que votre serveur reçoive le même webhook plus d'une fois. Vous devez utiliser le champ id pour vérifier si vous avez déjà traité l'événement.
2. Répondez rapidement : Renvoyez toujours un statut 200 OK immédiatement avant de télécharger des images ou de mettre à jour des bases de données.
3. Vérifiez toujours les webhooks : Envisagez d'implémenter un mécanisme de vérification (comme le jeton URL secret mentionné ci-dessus) pour vous assurer que les webhooks proviennent de notre service et empêcher les acteurs malveillants de falsifier les charges utiles.