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 des charges utiles d'événements au format json aux URL que vous spécifiez.

Pourquoi créer des Webhooks

L'utilisation des webhooks présente plusieurs avantages, notamment en ce qui concerne la vérification automatique des statuts des tâches API. Les webhooks nécessitent moins d'efforts et de coûts que de sonder continuellement l'API pour obtenir des 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 le sondage API. Cela vous permet également de mieux gérer vos limites de taux, surtout si vous sondez constamment.

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 "Créer un Webhook". Fournissez votre URL https souhaitée pour recevoir les webhooks et activez le webhook pour 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 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 traitée comme une livraison échouée.
  • Plusieurs échecs consécutifs peuvent :
    • Provoquer des retards ou un désordre dans l'ordre des mises à jour de progress
    • Désactiver automatiquement votre webhook après plusieurs tentatives (voir Politique de désactivation automatique)

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

Transférer des Webhooks pour les tests locaux

Si vous souhaitez tester votre code de 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 espace de code. Les étapes recommandées ci-dessous utilisent smee.io, mais vous pouvez utiliser tout service de votre choix pour générer une URL du proxy webhook.

Obtenez 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 des 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 transférés de 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 qui ressemble à 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 cela en cours d'exécution pendant que vous testez votre webhook. Lorsque vous souhaitez arrêter de transférer des webhooks, entrez Ctrl+C.
    Notez que le chemin est /webhook et le port est 3000. Ces valeurs peuvent être utiles lorsque vous souhaitez configurer votre propre code pour recevoir les livraisons de webhook plus tard.

Créez un webhook :

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

Réponse d'exemple

Lorsqu'un statut de tâche change, Meshy enverra une charge utile de webhook à votre URL 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, voir :