Webhooks

Haz que Meshy envíe una solicitud POST a tu servidor cuando una tarea de la API avance o finalice, así no necesitas hacer polling.

Por qué usar webhooks

Los webhooks requieren menos trabajo y cuestan menos que hacer polling del estado de la API para cada tarea. Meshy envía cada actualización en cuanto ocurre, por lo que la recibes antes, y los webhooks escalan mejor que el polling. Además, envías menos solicitudes, lo que te mantiene más alejado de tus límites de tasa.

Configurar un webhook

Para añadir un webhook, sigue estos pasos:

Abre la página de Webhooks en la Plataforma para Desarrolladores, y haz clic en Create Webhook.
En Payload URL, introduce la URL que recibirá las entregas. Meshy solo realiza entregas a través de https://.
Selecciona Active, y haz clic en Confirm.

Cada cuenta puede tener 5 webhooks activos, y 10 en total. Cada webhook activo recibe las actualizaciones de estado de todas tus tareas de la API.

Para probar un webhook con un servidor en tu equipo, consulta Probar en tu equipo.

Gestionar una entrega

Para aceptar una entrega, responde con un estado inferior a 400, como 200 o 202. Meshy espera unos 25 segundos la respuesta, así que guarda la entrega y responde primero. Realiza el trabajo lento después, como descargar el modelo.

Un estado de 400 o superior, o la ausencia de respuesta, cuenta como una entrega fallida. Meshy la reintenta con esperas más largas entre intentos, hasta 4 veces para una actualización IN_PROGRESS y hasta 9 veces para un estado final. Si 20 actualizaciones seguidas fallan en todos los intentos, Meshy puede desactivar el webhook. Para volver a activarlo, edítalo en la página de Webhooks y selecciona Active.

Escribe tu código teniendo en cuenta estos casos:

Las entregas pueden llegar desordenadas. Una entrega IN_PROGRESS puede llegar después de la final, así que no dejes que reemplace un estado final.
La misma actualización puede llegar más de una vez. Gestiona cada par de id y status una sola vez.

Si la entrega final de una tarea no ha llegado después de, aproximadamente, el doble del tiempo típico de la tarea, obtén la tarea desde su endpoint GET. Para conocer los tiempos típicos y cuánto esperar, consulta Ciclo de vida de la tarea.

Probar en tu equipo

Meshy solo realiza entregas a una URL pública https://, por lo que no puede llegar directamente a un servidor en tu equipo. Para probar código en tu equipo, reenvía una URL pública hacia él con un proxy de webhook. Estos pasos usan smee.io, y cualquier servicio de proxy de webhook funciona de la misma manera.

Abre smee.io y haz clic en Start a new channel. Copia la URL que aparece bajo Webhook Proxy URL.
Si todavía no tienes el cliente smee, instálalo:
```
npm install --global smee-client
```
Reenvía el canal a tu servidor. Reemplaza WEBHOOK_PROXY_URL por tu URL de proxy de webhook:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
La salida se ve así, donde WEBHOOK_PROXY_URL es tu URL de proxy de webhook:
```
Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
```
Mantenlo en ejecución mientras realizas las pruebas. Para detener el reenvío, pulsa Ctrl+C. Tu servidor recibe las entregas en el puerto 3000 en la ruta /webhook, así que configura tu código para escuchar ahí.
En la página de Webhooks, crea un webhook con la URL de proxy de webhook como su Payload URL.

Payload de entrega

Meshy envía una entrega mientras una tarea está IN_PROGRESS, y otra cuando la tarea alcanza un estado final. Una tarea puede alcanzar su estado final sin una entrega IN_PROGRESS.

Cada entrega es una solicitud POST a tu URL de payload con el objeto de la tarea como cuerpo JSON. Es el mismo objeto que devuelve el endpoint GET de la tarea, excepto progress. Una entrega envía progress como uno de estos valores:

50 mientras la tarea está IN_PROGRESS
100 cuando la tarea se completa con éxito
0 cuando la tarea falla o se cancela

Para conocer los campos de cada objeto de tarea, con un ejemplo, consulta las siguientes secciones: