Webhooks

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

Por Que Criar Webhooks

Usar webhooks tem várias vantagens, especialmente no que diz respeito a verificar automaticamente o status das tarefas de API. Webhooks exigem menos esforço e custos do que fazer polling contínuo da API para obter atualizações de status das tarefas. 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 para 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, atualmente só permitimos o envio de webhooks para URLs https. Se você deseja 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 (por exemplo, 200 OK, 202 Accepted).
  • Qualquer resposta com um código de status >= 400 será tratada como uma entrega falha.
  • Múltiplas falhas consecutivas podem:
    • Causar atrasos ou desordem nas atualizações de progresso
    • Desabilitar automaticamente seu webhook após tentativas repetidas (consulte a Política de Desativação Automática)

Dica: Sempre retorne uma resposta de sucesso após validar e armazenar o payload do webhook, mesmo que o processamento adicional ocorra de forma assíncrona.

Encaminhando Webhooks para Testes Locais

Se você deseja testar seu código de webhook localmente, o que normalmente ocorre 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 etapas de configuração a seguir.

Encaminhe webhooks:

  1. Se você 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 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 semelhante a 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, digite 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 posteriormente.

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 sua URL configurada. O payload contém o objeto da tarefa no formato JSON. Para uma descrição completa de todas as propriedades do objeto de tarefa e exemplos de payloads, consulte: