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. Depois de configurado, a Meshy enviará payloads (carga útil) de eventos no formato json via POST para as URLs que você especificar.

Por que criar Webhooks

Usar webhooks tem várias vantagens, especialmente em relação à verificação automática dos status das tarefas de API. Webhooks exigem menos esforço e custos do que consultar continuamente a API para obter atualizações de status das tarefas. Webhooks também permitem atualizações quase em tempo real e, no fim, escalam melhor do que a consulta da API. Isso também permite que você gerencie melhor seus limites de taxa, especialmente se estiver fazendo consultas constantemente.

Setup e configuração

Para habilitar webhooks, navegue até a página de configurações da API quando estiver conectado ao aplicativo web da Meshy. Encontre a seção "Webhooks" abaixo das suas chaves de API e clique no botão "Criar 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 está 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 (por exemplo, 200 OK, 202 Accepted).
  • Qualquer resposta com um código de status >= 400 será tratada como uma entrega com falha.
  • Múltiplas falhas consecutivas podem:
    • Fazer com que as atualizações de progress sejam atrasadas ou cheguem fora de ordem
    • Desabilitar automaticamente seu webhook após tentativas repetidas (consulte a Política de desativação automática)

Dica: Sempre retorne uma resposta de sucesso depois de validar e armazenar o payload do webhook, mesmo que o processamento adicional aconteça de forma assíncrona.

Encaminhando Webhooks para testes locais

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

Obter uma URL de proxy de webhook:

  1. No seu navegador, acesse https://smee.io/
  2. Clique em "Iniciar um novo canal"
  3. Copie a URL completa em "URL de proxy de webhook". Você usará esta URL nas etapas de setup a seguir.

Encaminhar webhooks:

  1. Se você ainda não tiver o smee-client instalado, execute o comando a seguir no seu terminal.
npm install --global smee-client
  1. Para receber webhooks encaminhados do smee.io, execute o comando a seguir 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 semelhante a esta, em que 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, insira 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.

Criar um webhook:

Agora você pode 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, a Meshy enviará um payload de webhook via POST para a URL configurada. O payload contém o objeto da tarefa em formato JSON. Para obter uma descrição completa de todas as propriedades do objeto da tarefa e payloads (carga útil) de exemplo, consulte: