lowpoly se retira el 30 oct 2026. Cambia de modelo antes de estas fechas para evitar errores en las solicitudes.

Webhooks

Los Webhooks te permiten recibir actualizaciones en tiempo real de Meshy cuando tus tareas de la API se completan o cambian de estado. Una vez configurados, Meshy enviará mediante POST los payloads de eventos en formato json a las URLs que especifiques.

Por qué crear Webhooks

Usar webhooks tiene varias ventajas, especialmente en lo referente a comprobar automáticamente el estado de las tareas de la API. Los webhooks requieren menos esfuerzo y costos que hacer polling continuamente a la API para obtener actualizaciones del estado de las tareas. Los webhooks también permiten actualizaciones casi en tiempo real y, en última instancia, escalan mejor que el polling de la API. Esto también te permite gestionar mejor tus límites de tasa, especialmente si estás haciendo polling constantemente.

Configuración y ajustes

Para habilitar los webhooks, abre la página de Webhooks en la Plataforma para Desarrolladores y haz clic en el botón "Create Webhook". Proporciona la URL https deseada para recibir los webhooks y habilita el webhook para recibir automáticamente las actualizaciones de tareas de Meshy. Puedes tener un máximo de 5 webhooks activos por cuenta de Meshy. Cuando un webhook está habilitado, todas las actualizaciones de estado de las tareas de la API se enviarán automáticamente a la URL de payload. Por motivos de seguridad, actualmente solo permitimos el envío de webhooks a URLs https. Si deseas configurar pruebas locales, consulta la siguiente sección.

Requisitos de entrega de Webhooks

Para que tu webhook funcione con normalidad y siga recibiendo eventos:

  • Tu servidor debe responder con un código de estado HTTP inferior a 400 (p. ej., 200 OK, 202 Accepted).
  • Cualquier respuesta con un código de estado >= 400 se considerará como una entrega fallida.
  • Varios fallos consecutivos pueden:
    • Provocar que las actualizaciones de progress se retrasen o lleguen desordenadas
    • Deshabilitar automáticamente tu webhook tras repetidos intentos (consulta la Política de deshabilitación automática)

Consejo: Devuelve siempre una respuesta de éxito después de validar y almacenar el payload del webhook, incluso si el procesamiento adicional ocurre de forma asíncrona.

Si el evento final de una tarea no ha llegado tras aproximadamente el doble de su tiempo habitual, obtén la tarea mediante su endpoint GET. Consulta Ciclo de vida de la tarea para conocer los tiempos habituales y cuánto esperar.

Reenvío de Webhooks para pruebas locales

Si deseas probar tu código de webhook localmente, que normalmente se encuentra en una dirección http, puedes usar una URL de proxy de webhook para reenviar los webhooks a tu computadora o codespace. A continuación se muestran los pasos recomendados usando smee.io, pero puedes usar cualquier servicio que desees para generar una URL de proxy de webhook.

Obtén una URL de proxy de webhook:

  1. En tu navegador, navega a https://smee.io/
  2. Haz clic en "Start a new channel"
  3. Copia la URL completa que aparece bajo "Webhook Proxy URL". Usarás esta URL en los siguientes pasos de configuración.

Reenvía los webhooks:

  1. Si aún no tienes instalado smee-client, ejecuta el siguiente comando en tu terminal.
npm install --global smee-client
  1. Para recibir los webhooks reenviados desde smee.io, ejecuta el siguiente comando en tu terminal. Reemplaza WEBHOOK_PROXY_URL con tu URL de proxy de webhook obtenida anteriormente.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Deberías ver una salida similar a esta, 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
  1. Mantén esto en ejecución mientras pruebas tu webhook. Cuando quieras detener el reenvío de webhooks, presiona Ctrl+C.
    Ten en cuenta que la ruta es /webhook y el puerto es 3000. Estos valores pueden ser útiles cuando quieras configurar tu propio código para recibir entregas de webhooks más adelante.

Crea un webhook:

Ahora puedes usar la URL de proxy de webhook para crear un nuevo webhook en la página de Webhooks.

Respuesta de ejemplo

Cuando el estado de una tarea cambia, Meshy enviará mediante POST un payload de webhook a tu URL configurada. El payload contiene el objeto de tarea en formato JSON. Para obtener una descripción completa de todas las propiedades del objeto de tarea y ejemplos de payloads, consulta: