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á los payloads de eventos en formato json a las URLs que especifiques.

Por qué crear Webhooks

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

Configuración y Ajustes

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. Encuentra la sección "Webhooks" debajo de tus API Keys y haz clic en el botón "Crear Webhook". Proporciona tu 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 la API se enviarán automáticamente a la URL de payload. Por razones de seguridad, solo permitimos enviar webhooks a URLs https en este momento. Si deseas configurar pruebas locales, consulta la siguiente sección.

Requisitos de entrega de Webhook

Para que tu webhook funcione normalmente y continúe recibiendo eventos:

  • Tu servidor debe responder con un código de estado HTTP por debajo de 400 (por ejemplo, 200 OK, 202 Accepted).
  • Cualquier respuesta con un código de estado >= 400 se tratará como una entrega fallida.
  • Múltiples fallos consecutivos pueden:
    • Causar que las actualizaciones de progress se retrasen o lleguen fuera de orden
    • Deshabilitar automáticamente tu webhook después de varios intentos (ver Política de Deshabilitación Automática)

Consejo: Siempre devuelve una respuesta de éxito después de validar y almacenar el payload del webhook, incluso si el procesamiento adicional ocurre de manera asincrónica.

Reenvío de Webhooks para pruebas locales

Si deseas probar tu código de webhook localmente, que típicamente está en una dirección http, puedes usar una URL de proxy de webhook para reenviar webhooks a tu computadora o espacio de código. A continuación se presentan 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 bajo "Webhook Proxy URL". Usarás esta URL en los siguientes pasos de configuración.

Reenviar 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 webhooks reenviados desde smee.io, ejecuta el siguiente comando en tu terminal. Reemplaza WEBHOOK_PROXY_URL con tu URL de proxy de webhook de antes.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Deberías ver una salida que 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
  1. Mantén esto en ejecución mientras pruebas tu webhook. Cuando quieras detener el reenvío de webhooks, ingresa Ctrl+C.
    Ten en cuenta que la ruta es /webhook y el puerto es 3000. Estos valores pueden ser útiles cuando desees 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á un payload de webhook a tu URL configurada. El payload contiene el objeto de la tarea en formato JSON. Para una descripción completa de todas las propiedades del objeto de tarea y ejemplos de payloads, consulta: