Webhooks

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

Pourquoi créer des Webhooks

L’utilisation de webhooks présente plusieurs avantages, notamment pour vérifier automatiquement les statuts des tâches API. Les Webhooks nécessitent moins d’efforts et de coûts que l’interrogation continue de l’API pour obtenir des mises à jour du statut des tâches. Les Webhooks permettent également des mises à jour quasi en temps réel et, au final, évoluent mieux que l’interrogation de l’API. Cela vous permet également de mieux gérer vos limites de débit, surtout si vous interrogez constamment l’API.

Configuration et paramétrage

Pour activer les webhooks, accédez à la page des paramètres de l’API lorsque vous êtes connecté à l’application web Meshy. Trouvez la section "Webhooks" sous vos clés API et cliquez sur le bouton "Create Webhook". Fournissez l’URL https souhaitée pour recevoir les webhooks et activez le webhook afin de recevoir automatiquement les mises à jour des tâches depuis 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 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 à recevoir des événements :

  • Votre serveur doit répondre avec un code de statut HTTP inférieur à 400 (par ex., 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 :
    • Entraîner le retard des mises à jour de progress ou leur arrivée dans le désordre
    • Désactiver automatiquement votre webhook après des tentatives répétées (voir la politique de désactivation automatique)

Conseil : 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.

Transfert des Webhooks pour les tests locaux

Si vous souhaitez tester votre code webhook localement, qui se trouve 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. Les étapes ci-dessous sont recommandées avec 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 smee-client n’est pas déjà installé, 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 une sortie 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. Gardez ceci en cours d’exécution pendant que vous testez votre webhook. Lorsque vous souhaitez arrêter de transférer les webhooks, saisissez Ctrl+C.
    Notez que le chemin est /webhook et que le port est 3000. Ces valeurs peuvent être utiles lorsque vous souhaiterez configurer votre propre code pour recevoir ultérieurement les livraisons de webhook.

Créer un webhook :

Vous pouvez maintenant utiliser l’URL du proxy webhook pour créer un nouveau webhook dans la page des paramètres de Meshy API.

Exemple de réponse

Lorsqu’un statut de tâche change, Meshy enverra par POST une charge utile webhook à votre URL configurée. La charge utile contient l’objet de 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 (payload), consultez :