Webhooks

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

Porquê criar Webhooks

A utilização de webhooks tem várias vantagens, especialmente no que diz respeito à verificação automática dos estados das tarefas da API. Os Webhooks exigem menos esforço e custos do que consultar continuamente 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 da API. Isto também lhe permite gerir melhor os seus limites de taxa, especialmente se estiver a consultar constantemente.

Instalação e configuração

Para ativar webhooks, aceda à página de definições da API quando tiver sessão iniciada na aplicação Web da Meshy. Encontre a secção "Webhooks" abaixo das suas API keys e clique no botão "Criar 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, neste momento apenas permitimos o envio de webhooks para URLs https. 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 tem de 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.
  • Várias falhas consecutivas podem:
    • Fazer com que as atualizações de progress sejam atrasadas ou cheguem fora de ordem
    • Desativar automaticamente o seu webhook após tentativas repetidas (consulte a 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.

Encaminhar Webhooks para testes locais

Se pretender testar o seu código de webhook localmente, que normalmente está num endereço http, pode utilizar um URL de proxy de webhook para encaminhar webhooks para o seu computador ou codespace. Abaixo encontram-se os passos recomendados utilizando smee.io, mas pode utilizar qualquer serviço que pretenda para gerar um URL de proxy de webhook.

Obter um URL de proxy de webhook:

  1. No seu navegador, aceda a https://smee.io/
  2. Clique em "Start a new channel"
  3. Copie o URL completo em "Webhook Proxy URL". Utilizará 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 de smee.io, execute o seguinte comando no seu terminal. Substitua WEBHOOK_PROXY_URL pelo seu URL de proxy de webhook anterior.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Deverá ver um resultado semelhante a este, em que 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, introduza Ctrl+C.
    Tenha em atenção 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 webhook posteriormente.

Criar um webhook:

Pode agora utilizar o URL de proxy de webhook para criar um novo webhook na página de definições da Meshy API.

Resposta de exemplo

Quando o estado de uma tarefa muda, a Meshy enviará um payload de webhook por POST 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 payloads (cargas úteis) de exemplo, consulte: