lowpoly sera retiré le 30 oct. 2026. Changez de modèle avant ces dates pour éviter les erreurs de requête.

Webhooks

Les Webhooks vous permettent de recevoir des mises à jour en temps réel de Meshy lorsque vos tâches d'API sont terminées ou changent de statut. Une fois configuré, Meshy enverra par POST des charges utiles d'événements au format json vers les URL que vous spécifiez.

Pourquoi créer des Webhooks

L'utilisation des webhooks présente plusieurs avantages, en particulier en ce qui concerne la vérification automatique des statuts des tâches d'API. Les webhooks demandent moins d'efforts et de coûts que l'interrogation continue de l'API pour obtenir les mises à jour de statut des tâches. Les webhooks permettent également des mises à jour quasi en temps réel et s'adaptent finalement mieux que l'interrogation de l'API. Cela vous permet également de mieux gérer vos limites de débit, en particulier si vous effectuez une interrogation constante.

Configuration

Pour activer les webhooks, ouvrez la page Webhooks dans la Plateforme développeur et cliquez sur le bouton « Create Webhook ». Fournissez l'URL https souhaitée pour recevoir les webhooks et activez le webhook pour recevoir automatiquement les mises à jour de tâches de Meshy. Vous pouvez avoir un maximum de 5 webhooks actifs par compte Meshy. Lorsqu'un webhook est activé, toutes les mises à jour de statut des tâches d'API seront automatiquement envoyées à l'URL de payload. Pour des raisons de sécurité, nous n'autorisons actuellement l'envoi de webhooks qu'aux URL https. Si vous souhaitez configurer des tests locaux, consultez la section suivante.

Exigences de livraison des Webhooks

Pour que votre webhook fonctionne normalement et continue de recevoir des événements :

  • Votre serveur doit répondre avec un code de statut HTTP inférieur à 400 (par exemple, 200 OK, 202 Accepted).
  • Toute réponse avec un code de statut >= 400 sera considérée comme une livraison échouée.
  • Plusieurs échecs consécutifs peuvent :
    • Entraîner un retard ou un désordre dans les mises à jour de progression
    • Désactiver automatiquement votre webhook après des tentatives répétées (voir la politique de désactivation automatique)

Astuce : Renvoyez toujours une réponse de succès après avoir validé et stocké la charge utile du webhook, même si le traitement ultérieur se produit de manière asynchrone.

Si l'événement final d'une tâche n'est pas arrivé après environ deux fois son délai habituel, récupérez la tâche via son point de terminaison GET. Consultez Cycle de vie d'une tâche pour connaître les délais habituels et le temps d'attente recommandé.

Transférer les Webhooks pour les tests locaux

Si vous souhaitez tester votre code de webhook localement, ce qui se fait généralement à une adresse http, vous pouvez utiliser une URL du proxy webhook pour transférer les webhooks vers votre ordinateur ou votre codespace. Voici les étapes recommandées en utilisant smee.io, mais vous pouvez utiliser le service de votre choix pour générer une URL du proxy webhook.

Obtenir une URL du proxy webhook :

  1. Dans votre navigateur, accédez à https://smee.io/
  2. Cliquez sur « Start a new channel »
  3. Copiez l'URL complète sous « Webhook Proxy URL ». Vous utiliserez cette URL dans les étapes de configuration suivantes.

Transférer les webhooks :

  1. Si vous n'avez pas déjà installé smee-client, exécutez la commande suivante dans votre terminal.
npm install --global smee-client
  1. Pour recevoir les webhooks transférés depuis smee.io, exécutez la commande suivante dans votre terminal. Remplacez WEBHOOK_PROXY_URL par votre URL du proxy webhook obtenue précédemment.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Vous devriez voir un résultat ressemblant à ceci, où WEBHOOK_PROXY_URL est votre URL du proxy webhook :

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Laissez ceci s'exécuter pendant que vous testez votre webhook. Lorsque vous souhaitez arrêter le transfert des webhooks, appuyez sur Ctrl+C.
    Notez que le chemin est /webhook et le port est 3000. Ces valeurs peuvent vous être utiles lorsque vous souhaitez configurer votre propre code pour recevoir les livraisons de webhooks par la suite.

Créer un webhook :

Vous pouvez maintenant utiliser l'URL du proxy webhook pour créer un nouveau webhook sur la page Webhooks.

Exemple de réponse

Lorsque le statut d'une tâche change, Meshy enverra par POST une charge utile de webhook à l'URL que vous avez configurée. La charge utile contient l'objet tâche au format JSON. Pour une description complète de toutes les propriétés de l'objet tâche et des exemples de charges utiles, consultez :