Webhooks pour les événements de devis et de travaux

Qu'est-ce que les Webhooks ?

Les Webhooks permettent à votre application de recevoir des notifications en temps réel concernant les événements se produisant dans Quote3D. Au lieu d'interroger notre API pour des mises à jour (par exemple, pour vérifier si un devis est terminé), Quote3D enverra une requête HTTP POST à une URL que vous spécifiez dès qu'un événement se produit.

Ceci est beaucoup plus efficace et vous permet de déclencher des flux de travail automatisés dans votre propre système, tels que la mise à jour d'un statut de commande, la notification d'un client ou le démarrage d'un travail de production.

Événements disponibles

• quote.completed: Déclenché lorsqu'un calcul de devis d'impression 3D est terminé avec succès.
• quote.failed: Déclenché si un calcul de devis échoue pour quelque raison que ce soit.
• file.uploaded: Déclenché lorsqu'un nouveau fichier modèle est téléchargé avec succès sur votre compte.
• file.deleted: Déclenché lorsqu'un fichier modèle est supprimé de votre stockage.
• job.status_changed : déclenché à chaque transition d'état d'un travail asynchrone (queued, processing, completed, failed). Un seul devis en produit plusieurs.
• widget.added_to_cart: Déclenché lorsqu'un client ajoute un modèle à son panier en utilisant votre widget intégrable.

Exigences du point de terminaison

L'URL de votre point de terminaison est validée à l'enregistrement, puis avant chaque tentative de livraison. Les URL qui échouent à ces règles sont rejetées avec une réponse 400.

• Doit utiliser http ou https. Les autres schémas sont rejetés.
• Ne doit pas contenir d'identifiants. https://user:[email protected] est rejeté.
• Ne doit pas se résoudre vers une adresse privée ou réservée : localhost, boucle locale, lien-local (y compris les métadonnées d'instance cloud), plages privées, CGNAT, multidiffusion et espace réservé.
• Le nom d'hôte est résolu par DNS à chaque tentative : un nom d'hôte public pointant vers un espace privé est donc rejeté lui aussi.
• Les redirections ne sont pas suivies. Renvoyez votre réponse directement depuis l'URL enregistrée.

Exemple de charge utile

Toutes les requêtes webhook sont envoyées au format JSON. Voici un exemple de charge utile pour l'événement quote.completed :

{
  "event": "quote.completed",
  "timestamp": "2026-03-10T14:30:00.000Z",
  "data": {
    "jobId": "job_01HXYZ123456789",
    "quoteId": "job_01HXYZ123456789",
    "status": "completed",
    "fileName": "gearbox-housing.stl",
    "fileId": "fl_987654321",
    "processingTimeMs": 22134,
    "result": {
      "quote_id": "job_01HXYZ123456789",
      "total_price": 25.5,
      "currency": "USD",
      "estimated_time": "2h 15m",
      "estimated_time_seconds": 8100,
      "filament_weight": 42.8,
      "printInfo": {
        "technology": "FDM",
        "material": "PLA",
        "color": "Black"
      }
    },
    "error": null
  }
}

Sécurité et Vérification

Pour garantir que les requêtes webhook proviennent bien de Quote3D et n'ont pas été altérées, nous incluons une signature HMAC-SHA256 dans l'en-tête X-Webhook-Signature.

Lorsque vous créez un webhook dans le tableau de bord, une Clé Secrète unique vous sera affichée. Vous devez utiliser cette clé pour vérifier la signature de chaque requête entrante.

Étapes de vérification :

1. Lisez le corps de la requête brute sous forme de chaîne de caractères.
2. Récupérez la signature de l'en-tête X-Webhook-Signature et le nom de l'événement de X-Webhook-Event.
3. Calculez le hachage HMAC-SHA256 du corps brut en utilisant votre Clé Secrète Webhook.
4. Préfixez votre hachage calculé avec sha256= et comparez-le à la signature. S'ils correspondent, la requête est authentique.

const crypto = require('crypto');

// Secret Key from your Quote3D Dashboard
const SECRET = 'your_webhook_secret_here';

function verifySignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const event = req.headers['x-webhook-event'];
  const body = req.rawBody; // Keep the exact raw JSON string

  const hmac = crypto.createHmac('sha256', SECRET);
  const digest = 'sha256=' + hmac.update(body).digest('hex');

  if (typeof signature !== 'string' || typeof event !== 'string') {
    return false;
  }

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(digest, 'utf8');

  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

Gestion des Webhooks

Vous pouvez gérer vos webhooks directement depuis le Tableau de bord :

1. Accédez à la page Webhooks dans votre tableau de bord.
2. Cliquez sur Nouveau Webhook pour ajouter un nouveau point de terminaison.
3. Saisissez l'URL de votre point de terminaison et sélectionnez les événements à écouter. HTTPS est fortement recommandé ; voir les Exigences ci-dessus.
4. Copiez immédiatement votre Clé Secrète et conservez-la en lieu sûr. Vous ne pourrez plus la voir !
5. Associez éventuellement un jeton d'API. Laissez le champ vide et le webhook se déclenche pour chaque requête de votre compte ; associez un jeton et il ne se déclenche que pour les requêtes effectuées avec ce jeton.

Réessayer les livraisons ayant échoué

Reprises automatiques

Une livraison en échec est relancée automatiquement avant même que vous n'ayez à intervenir. Les livraisons sont tentées jusqu'à 3 fois ; au-delà, la livraison est close en échec et reste visible dans le tableau de bord.

• La première tentative a lieu dès le déclenchement de l'événement. Les tentatives suivantes sont prises en charge par un balayage en arrière-plan : l'intervalle pratique entre tentatives dépend donc de ce balayage plutôt que d'un nombre fixe de secondes.
• Si notre processus est interrompu en pleine tentative, la livraison est récupérée et relancée plutôt que perdue.
• Chaque livraison est réservée de façon atomique avant l'envoi : une reprise n'aboutit donc jamais à un double envoi simultané de la même livraison.
• Une reprise envoie exactement le même corps et la même signature X-Webhook-Signature que la tentative initiale : votre logique de vérification existante fonctionne sans modification.

Si une destination webhook était temporairement indisponible ou a renvoyé une erreur, vous pouvez inspecter la livraison dans le tableau de bord et déclencher un renvoi pour cet enregistrement de livraison spécifique.

Meilleures pratiques

• Retournez immédiatement un statut 200 OK pour accuser réception du webhook.
• Effectuez le traitement lourd de manière asynchrone (par exemple, en utilisant une file d'attente de tâches en arrière-plan) pour éviter un dépassement de temps.
• Vérifiez toujours la signature pour protéger votre point de terminaison contre les requêtes non autorisées.
• Idempotence : Assurez-vous que votre système peut gérer le même webhook plusieurs fois sans problème, car nous pouvons réessayer les livraisons en cas d'erreurs transitoires.