lowpoly será descontinuado em 30 de out. de 2026. Troque de modelo antes dessas datas para evitar erros nas solicitações.

Webhooks

Webhooks permitem que você receba atualizações em tempo real da Meshy quando suas tarefas de API forem concluídas ou mudarem de status. Uma vez configurado, a Meshy enviará via POST os payloads de eventos em formato json para as URLs que você especificar.

Por Que Criar Webhooks

Usar webhooks tem diversas vantagens, especialmente no que diz respeito a verificar automaticamente o status das tarefas da API. Os webhooks exigem menos esforço e custos do que fazer polling contínuo da API para obter atualizações de status das tarefas. Os webhooks também permitem atualizações quase em tempo real e, em última análise, escalam melhor do que o polling da API. Isso também permite que você gerencie melhor seus limites de taxa, especialmente se estiver fazendo polling constantemente.

Configuração e Ajustes

Para habilitar webhooks, abra a página de Webhooks na Plataforma de Desenvolvedores e clique no botão "Create Webhook". Forneça a URL https desejada para receber webhooks e habilite o webhook para receber automaticamente atualizações de tarefas da Meshy. Você pode ter no máximo 5 webhooks ativos por conta Meshy. Quando um webhook é habilitado, todas as atualizações de status de tarefas da API serão enviadas automaticamente para a URL de payload. Por motivos de segurança, no momento só permitimos o envio de webhooks para URLs https. Se você quiser configurar testes locais, consulte a seção a seguir.

Requisitos de Entrega de Webhook

Para que seu webhook funcione normalmente e continue recebendo eventos:

  • Seu servidor deve responder com um código de status HTTP abaixo de 400 (ex.: 200 OK, 202 Accepted).
  • Qualquer resposta com código de status >= 400 será tratada como uma falha de entrega.
  • Múltiplas falhas consecutivas podem:
    • Fazer com que as atualizações de progresso sejam atrasadas ou cheguem fora de ordem
    • Desabilitar automaticamente seu webhook após tentativas repetidas (veja a Política de Desabilitação Automática)

Dica: Sempre retorne 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 cerca do dobro do tempo típico, busque a tarefa usando seu endpoint GET. Veja Ciclo de Vida da Tarefa para tempos típicos e quanto tempo esperar.

Encaminhando Webhooks para Testes Locais

Se você quiser testar seu código de webhook localmente, que geralmente está em um endereço http, você pode usar uma URL de proxy de webhook para encaminhar webhooks para seu computador ou codespace. Abaixo estão os passos recomendados usando o smee.io, mas você pode usar qualquer serviço que desejar para gerar uma URL de proxy de webhook.

Obtenha uma URL de proxy de webhook:

  1. No seu navegador, navegue até https://smee.io/
  2. Clique em "Start a new channel"
  3. Copie a URL completa em "Webhook Proxy URL". Você usará essa URL nas próximas etapas de configuração.

Encaminhe webhooks:

  1. Se você ainda não tem o smee-client instalado, execute o seguinte comando no seu terminal.
npm install --global smee-client
  1. Para receber webhooks encaminhados do smee.io, execute o seguinte comando no seu terminal. Substitua WEBHOOK_PROXY_URL pela sua URL de proxy de webhook obtida anteriormente.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Você deverá ver uma saída parecida com esta, onde WEBHOOK_PROXY_URL é sua URL de proxy de webhook:

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

Crie um webhook:

Agora você pode usar a URL de proxy de webhook para criar um novo webhook na página de Webhooks.

Exemplo de Resposta

Quando o status de uma tarefa muda, a Meshy enviará via POST um payload de webhook para a URL que você configurou. O payload contém o objeto da tarefa em formato JSON. Para uma descrição completa de todas as propriedades do objeto de tarefa e exemplos de payloads, veja: