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 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 del estado de las tareas. Los webhooks también permiten actualizaciones casi en tiempo real y, en última instancia, escalan mejor que el sondeo de la API. Esto también te permite gestionar mejor tus límites de tasa, especialmente si estás sondeando constantemente.

Configuración

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 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 (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:
    • Provocar que las actualizaciones de progress se retrasen o lleguen fuera de orden
    • Deshabilitar automáticamente tu webhook después de 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 se encuentra 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 recomiendan los pasos 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 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 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 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 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: