Webhooks

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é à différentes étapes d'un travail de traitement asynchrone.
• widget.added_to_cart: Déclenché lorsqu'un client ajoute un modèle à son panier en utilisant votre widget intégrable.

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. Entrez l'URL de votre point de terminaison (doit être HTTPS) et sélectionnez les événements que vous souhaitez surveiller.
4. Copiez immédiatement votre Clé Secrète et conservez-la en lieu sûr. Vous ne pourrez plus la voir !
5. Fournissez un lien de Jeton API facultatif si vous souhaitez que le webhook ne se déclenche que pour les actions effectuées avec ce jeton spécifique.

Réessayer les livraisons ayant échoué

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.