Webhooks
Demandez à Meshy d'envoyer une requête POST à votre serveur lorsqu'une tâche de l'API progresse ou se termine, afin que vous n'ayez pas besoin d'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 connaître le statut de chaque tâche. Meshy envoie chaque mise à jour au fur et à mesure qu'elle se produit, vous la recevez donc plus tôt, et les webhooks s'adaptent mieux à la montée en charge que l'interrogation. Vous envoyez également moins de requêtes, ce qui vous éloigne de vos limites de débit.
Configurer un webhook
Pour ajouter un webhook, suivez ces étapes :
- Ouvrez la page Webhooks dans la Developer Platform, puis cliquez sur Create Webhook.
- Dans Payload URL, saisissez l'URL qui recevra les livraisons. Meshy ne livre que via
https://. - Conservez une copie du Webhook Secret que la boîte de dialogue remplit automatiquement. Chaque livraison le porte, afin que votre serveur puisse vérifier qu'une requête provient bien de Meshy. Pour un webhook que vous possédez déjà, cliquez sur l'icône en forme d'œil dans sa colonne Secret pour le voir.
- 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.
Traiter une livraison
Pour accepter une livraison, répondez avec un statut inférieur à 400, comme 200 ou 202. Meshy attend environ 25 secondes la réponse, alors enregistrez d'abord la livraison et répondez en premier. Effectuez ensuite le travail plus long, comme le téléchargement du modèle.
Un statut de 400 ou plus, ou une absence de réponse, est considéré comme une livraison échouée. Meshy la relance avec des délais de plus en plus longs 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 des cas suivants :
- Les livraisons peuvent arriver dans le désordre. Une livraison
IN_PROGRESSpeut arriver après la livraison finale, alors ne la laissez pas remplacer un statut final. - La même mise à jour peut arriver plus d'une fois. Traitez chaque paire
idetstatusune seule fois. - Toute personne qui connaît votre URL peut lui envoyer une requête. Comparez
X-MESHY-API-WEBHOOK-SECRET-KEYavec votre copie du secret, et rejetez toute requête qui ne correspond pas.
Si la livraison finale d'une tâche n'est pas arrivée après environ le double de 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, redirigez une URL publique vers celui-ci 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 -
Redirigez le canal vers votre serveur. Remplacez
WEBHOOK_PROXY_URLpar votre URL du proxy webhook :smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000La sortie ressemble à ceci, où
WEBHOOK_PROXY_URLest votre URL du proxy webhook :Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook Connected WEBHOOK_PROXY_URLLaissez-le fonctionner pendant vos tests. Pour arrêter la redirection, appuyez sur Ctrl+C. Votre serveur reçoit les livraisons sur le port
3000au 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 les en-têtes suivants :
| En-tête | Valeur |
|---|---|
X-MESHY-API-WEBHOOK-SECRET-KEY | Le secret du webhook |
X-MESHY-API-WEBHOOK-USER-ID | L'ID de l'utilisateur Meshy propriétaire du webhook |
Meshy-Webhook-Version | v1, le format du corps |
Content-Type | application/json |
User-Agent | MeshyAPIWebhook/1.0.0 |
Le corps JSON est l'objet tâche. C'est le 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 :
50pendant que la tâche estIN_PROGRESS100lorsque la tâche réussit0lorsque la tâche échoue ou est annulée
Pour les champs de chaque objet tâche, avec un exemple, consultez les sections suivantes :