Webhooks

Webhooks permitem que você receba atualizações em tempo real do Meshy quando suas tarefas de API são concluídas ou mudam de status. Uma vez configurado, o Meshy enviará payloads de eventos 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 os status das tarefas da API. Webhooks requerem menos esforço e custos do que consultar continuamente a API para obter atualizações de status de tarefas. Webhooks também permitem atualizações quase em tempo real e, em última análise, escalam melhor do que a consulta da API. Isso também permite que você gerencie melhor seus limites de taxa, especialmente se você estiver consultando constantemente.

Configuração e Ajustes

Para habilitar webhooks, navegue até a página de configurações da API ao fazer login no aplicativo web Meshy. Encontre a seção "Webhooks" abaixo das suas API Keys e clique no botão "Criar Webhook". Forneça sua URL https desejada para receber webhooks e habilite o webhook para receber automaticamente atualizações de tarefas do Meshy. Você pode ter no máximo 5 webhooks ativos por conta Meshy. Quando um webhook está habilitado, todas as atualizações de status das tarefas da API serão automaticamente enviadas para a URL de payload. Por motivos de segurança, só permitimos o envio de webhooks para URLs https neste momento. Se você gostaria de configurar testes locais, veja 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 falhada.
  • Falhas consecutivas múltiplas podem:
    • Causar atrasos nas atualizações de progress ou chegarem fora de ordem
    • Desabilitar automaticamente seu webhook após tentativas repetidas (veja 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.

Encaminhamento de Webhooks para Testes Locais

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

Obter 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á esta URL nas etapas de configuração a seguir.

Encaminhar 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 de antes.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Você deve ver uma saída que se parece com isto, 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 você testa seu webhook. Quando quiser parar de encaminhar webhooks, pressione Ctrl+C.
    Note 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.

Criar um webhook:

Você pode agora usar a URL de proxy de webhook para criar um novo webhook na página de configurações da Meshy API.

Resposta de Exemplo

Quando o status de uma tarefa muda, o Meshy enviará um payload de webhook para sua URL configurada. 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: