Webhooks

Demandez à Meshy d'envoyer une requête POST à votre serveur lorsqu'une tâche API progresse ou se termine, afin de ne pas avoir à interroger l'API.

Pourquoi utiliser les webhooks

Les webhooks demandent moins de travail et coûtent moins cher que l'interrogation de l'API pour le statut de chaque tâche. Meshy envoie chaque mise à jour dès qu'elle se produit, vous l'obtenez donc plus tôt, et les webhooks s'adaptent mieux que l'interrogation. Vous envoyez également moins de requêtes, ce qui vous éloigne davantage de vos limites de débit.

Configurer un webhook

Pour ajouter un webhook, suivez ces étapes :

Ouvrez la page Webhooks dans la Plateforme de développement, et cliquez sur Create Webhook.
Dans Payload URL, saisissez l'URL qui reçoit les livraisons. Meshy ne livre que via https://.
Sélectionnez Active, puis cliquez sur Confirm.

Chaque compte peut avoir 5 webhooks actifs, et 10 au total. Chaque webhook actif reçoit les mises à jour de statut de toutes vos tâches API.

Pour tester un webhook avec un serveur sur votre ordinateur, consultez Tester sur votre ordinateur.

Gérer une livraison

Pour accepter une livraison, répondez avec un statut inférieur à 400, par exemple 200 ou 202. Meshy attend environ 25 secondes la réponse, donc stockez la livraison et répondez d'abord. Effectuez ensuite le travail plus lent, comme le téléchargement du modèle.

Un statut de 400 ou plus, ou l'absence de réponse, est considéré comme une livraison échouée. Meshy la retente avec des attentes plus longues entre les tentatives, jusqu'à 4 fois pour une mise à jour IN_PROGRESS et jusqu'à 9 fois pour un statut final. Si 20 mises à jour consécutives échouent à chaque tentative, Meshy peut désactiver le webhook. Pour le réactiver, modifiez-le sur la page Webhooks et sélectionnez Active.

Écrivez votre code en tenant compte de ces cas :

Les livraisons peuvent arriver dans le désordre. Une livraison IN_PROGRESS peut arriver après la livraison finale, ne la laissez donc pas remplacer un statut final.
La même mise à jour peut arriver plus d'une fois. Traitez chaque paire id et status une seule fois.

Si la livraison finale d'une tâche n'est pas arrivée après environ deux fois la durée habituelle de la tâche, récupérez la tâche depuis son point de terminaison GET. Pour les durées habituelles et le temps d'attente, consultez Cycle de vie d'une tâche.

Tester sur votre ordinateur

Meshy ne livre qu'à une URL publique https://, elle ne peut donc pas atteindre directement un serveur sur votre ordinateur. Pour tester du code sur votre ordinateur, transférez-lui une URL publique avec un proxy webhook. Ces étapes utilisent smee.io, et tout service de proxy webhook fonctionne de la même manière.

Ouvrez smee.io et cliquez sur Start a new channel. Copiez l'URL sous Webhook Proxy URL.
Si vous n'avez pas encore le client smee, installez-le :
```
npm install --global smee-client
```
Transférez le canal vers votre serveur. Remplacez WEBHOOK_PROXY_URL par votre URL du proxy webhook :
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
La sortie 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
```
Laissez-le fonctionner pendant vos tests. Pour arrêter le transfert, appuyez sur Ctrl+C. Votre serveur reçoit les livraisons sur le port 3000 au chemin /webhook, configurez donc votre code pour écouter à cet endroit.
Sur la page Webhooks, créez un webhook avec l'URL du proxy webhook comme Payload URL.

Charge utile de livraison

Meshy envoie une livraison pendant qu'une tâche est IN_PROGRESS, et une autre lorsque la tâche atteint un statut final. Une tâche peut atteindre son statut final sans livraison IN_PROGRESS.

Chaque livraison est une requête POST vers votre URL de payload avec l'objet tâche comme corps JSON. Il s'agit du même objet que celui renvoyé par le point de terminaison GET de la tâche, à l'exception de progress. Une livraison envoie progress comme l'une de ces valeurs :

50 pendant que la tâche est IN_PROGRESS
100 lorsque la tâche réussit
0 lorsque la tâche échoue ou est annulée

Pour les champs de chaque objet tâche, avec un exemple, consultez les sections suivantes :