lowpoly será descontinuado a 30/10/2026. Mude de modelo antes destas datas para evitar erros nos pedidos.

Webhooks

Os Webhooks permitem-lhe receber atualizações em tempo real da Meshy quando as suas tarefas de API são concluídas ou mudam de estado. Uma vez configurados, a Meshy enviará (POST) payloads de eventos em formato json para os URLs que especificar.

Porque Criar Webhooks

Usar webhooks tem várias vantagens, especialmente no que diz respeito à verificação automática dos estados das tarefas da API. Os webhooks requerem menos esforço e custos do que estar continuamente a consultar a API para obter atualizações do estado das tarefas. Os webhooks também permitem atualizações quase em tempo real e, em última análise, escalam melhor do que a consulta repetida da API. Isto também lhe permite gerir melhor os seus limites de taxa, especialmente se estiver a fazer consultas constantes.

Configuração

Para ativar os webhooks, abra a página de Webhooks na Developer Platform e clique no botão "Create Webhook". Forneça o URL https pretendido para receber webhooks e ative o webhook para receber automaticamente atualizações de tarefas da Meshy. Pode ter um máximo de 5 webhooks ativos por conta Meshy. Quando um webhook está ativado, todas as atualizações de estado das tarefas da API serão enviadas automaticamente para o URL de payload. Por motivos de segurança, apenas permitimos o envio de webhooks para URLs https neste momento. Se pretender configurar testes locais, consulte a secção seguinte.

Requisitos de Entrega de Webhooks

Para que o seu webhook funcione normalmente e continue a receber eventos:

  • O seu servidor deve responder com um código de estado HTTP abaixo de 400 (por exemplo, 200 OK, 202 Accepted).
  • Qualquer resposta com um código de estado >= 400 será tratada como uma entrega falhada.
  • Múltiplas falhas consecutivas podem:
    • Causar atrasos nas atualizações de progress ou fazê-las chegar fora de ordem
    • Desativar automaticamente o seu webhook após tentativas repetidas (ver Política de Desativação Automática)

Dica: Devolva sempre uma resposta de sucesso depois de validar e armazenar o payload do webhook, mesmo que o processamento adicional ocorra de forma assíncrona.

Se o evento final de uma tarefa não chegar depois de aproximadamente o dobro do seu tempo típico, obtenha a tarefa através do seu endpoint GET. Consulte Task Lifecycle para tempos típicos e quanto tempo esperar.

Encaminhar Webhooks para Testes Locais

Se pretender testar o código do seu webhook localmente, que tipicamente está num endereço http, pode usar um URL de proxy de webhook para encaminhar webhooks para o seu computador ou codespace. Os passos abaixo são recomendados usando smee.io, mas pode usar qualquer serviço que desejar para gerar um URL de proxy de webhook.

Obtenha um URL de proxy de webhook:

  1. No seu navegador, navegue para https://smee.io/
  2. Clique em "Start a new channel"
  3. Copie o URL completo em "Webhook Proxy URL". Usará este URL nos passos de configuração seguintes.

Encaminhar webhooks:

  1. Se ainda não tiver o smee-client instalado, execute o seguinte comando no seu terminal.
npm install --global smee-client
  1. Para receber webhooks encaminhados a partir do smee.io, execute o seguinte comando no seu terminal. Substitua WEBHOOK_PROXY_URL pelo seu URL de proxy de webhook obtido anteriormente.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Deverá ver uma saída semelhante a esta, onde WEBHOOK_PROXY_URL é o seu URL de proxy de webhook:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Mantenha isto em execução enquanto testa o seu webhook. Quando quiser parar de encaminhar webhooks, prima Ctrl+C.
    Note que o caminho é /webhook e a porta é 3000. Estes valores podem ser úteis quando quiser configurar o seu próprio código para receber entregas de webhooks mais tarde.

Criar um webhook:

Pode agora usar o URL de proxy de webhook para criar um novo webhook na página de Webhooks.

Exemplo de Resposta

Quando o estado de uma tarefa muda, a Meshy enviará (POST) um payload de webhook para o URL configurado. O payload contém o objeto da tarefa em formato JSON. Para uma descrição completa de todas as propriedades do objeto da tarefa e exemplos de payloads, consulte: