Webhooks

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

Pourquoi créer des Webhooks

L'utilisation des webhooks présente plusieurs avantages, notamment pour vérifier automatiquement le statut des tâches API. Les webhooks demandent moins d'efforts et de coûts que le fait d'interroger continuellement l'API pour obtenir les mises à jour de statut des tâches. Les webhooks permettent également des mises à jour quasi instantanées et offrent finalement une meilleure évolutivité que le polling de l'API. Cela vous permet aussi de mieux gérer vos limites de débit, en particulier si vous effectuez des requêtes en continu.

Configuration et mise en place

Pour activer les webhooks, ouvrez la page Webhooks dans la Developer Platform et cliquez sur le bouton « Create Webhook ». Indiquez l'URL https souhaitée pour recevoir les webhooks et activez le webhook afin de recevoir automatiquement les mises à jour des 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 API sont automatiquement envoyées à l'URL de payload. Pour des raisons de sécurité, nous n'autorisons actuellement l'envoi de webhooks que vers des URLs 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 traitée comme une livraison échouée.
  • Plusieurs échecs consécutifs peuvent :
    • Provoquer un retard ou un désordre dans l'arrivée des mises à jour de progress
    • 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 fait de manière asynchrone.

Redirection des Webhooks pour les tests locaux

Si vous souhaitez tester votre code de webhook localement, généralement disponible à une adresse http, vous pouvez utiliser une URL du proxy webhook pour rediriger 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.

Rediriger les webhooks :

  1. Si vous n'avez pas encore installé smee-client, exécutez la commande suivante dans votre terminal.
npm install --global smee-client
  1. Pour recevoir les webhooks redirigé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 similaire à celui-ci, où WEBHOOK_PROXY_URL correspond à votre URL du proxy webhook :

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Laissez ce processus en cours d'exécution pendant que vous testez votre webhook. Lorsque vous souhaitez arrêter la redirection des webhooks, appuyez sur Ctrl+C.
    Notez que le chemin est /webhook et le port est 3000. Ces valeurs peuvent s'avérer utiles lorsque vous souhaiterez configurer votre propre code pour recevoir les livraisons de webhooks ultérieurement.

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 envoie une charge utile de webhook à l'URL que vous avez configurée. La charge utile contient l'objet de la tâche au format JSON. Pour une description complète de toutes les propriétés de l'objet de tâche et des exemples de charges utiles, consultez :