Webhooks

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

Por qué crear Webhooks

Usar webhooks tiene varias ventajas, especialmente en lo que respecta a comprobar automáticamente los estados de las tareas de API. Los Webhooks requieren menos esfuerzo y costes que consultar continuamente 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 las consultas a la API. Esto también te permite gestionar mejor tus límites de tasa, especialmente si estás consultando constantemente.

Instalación y configuración

Para habilitar los Webhooks, navega a la página de configuración de la API cuando hayas iniciado sesión en la aplicación web de Meshy. Busca la sección "Webhooks" debajo de tus claves de API y haz clic en el botón "Create Webhook". Proporciona la URL https deseada para recibir Webhooks y habilita el webhook para recibir automáticamente 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 API se enviarán automáticamente a la URL de payload. Por motivos de seguridad, en este momento solo permitimos enviar Webhooks a URL https. Si deseas configurar pruebas locales, consulta la siguiente sección.

Requisitos de entrega de Webhooks

Para que tu webhook funcione normalmente 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 tratará como una entrega fallida.
  • Varios fallos consecutivos pueden:
    • Hacer que las actualizaciones de progress se retrasen o lleguen fuera de orden
    • Deshabilitar automáticamente tu webhook tras intentos repetidos (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 posterior ocurre de forma asíncrona.

Reenvío de Webhooks para pruebas locales

Si deseas probar tu código de webhook localmente, que normalmente está en una dirección http, puedes usar una URL de proxy de webhook para reenviar 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.

Obtener 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 debajo de "Webhook Proxy URL". Usarás esta URL en los siguientes pasos de configuración.

Reenviar Webhooks:

  1. Si aún no tienes smee-client instalado, ejecuta el siguiente comando en tu terminal.
npm install --global smee-client
  1. Para recibir Webhooks reenviados desde smee.io, ejecuta el siguiente comando en tu terminal. Reemplaza WEBHOOK_PROXY_URL con tu URL de proxy de webhook anterior.
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 dejar de reenviar Webhooks, introduce Ctrl+C.
    Ten en cuenta que la ruta es /webhook y el puerto es 3000. Estos valores pueden resultar útiles cuando quieras configurar tu propio código para recibir entregas de webhook más adelante.

Crear un webhook:

Ahora puedes usar la URL de proxy de webhook para crear un nuevo webhook en la página de configuración de Meshy API.

Respuesta de ejemplo

Cuando cambia el estado de una tarea, Meshy enviará mediante POST un payload de webhook a la URL que hayas configurado. 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 payloads de ejemplo, consulta: