Webhooks

Os Webhooks permitem que recebas atualizações em tempo real do Meshy quando as tuas tarefas da API são concluídas ou mudam de estado. Uma vez configurados, o Meshy enviará payloads de eventos em formato json para os URLs que especificares.

Porque Criar Webhooks

Usar webhooks tem várias vantagens, especialmente no que diz respeito a verificar automaticamente os estados das tarefas da API. Os Webhooks requerem menos esforço e custos do que a sondagem contínua da API para obter atualizações de estado das tarefas. Os Webhooks também permitem atualizações quase em tempo real e, em última análise, escalam melhor do que a sondagem da API. Isto também te permite gerir melhor os teus limites de taxa, especialmente se estiveres a sondar constantemente.

Configuração e Definições

Para ativar os webhooks, navega até à página de definições da API quando estiveres logado na aplicação web Meshy. Encontra a secção "Webhooks" abaixo das tuas API Keys e clica no botão "Criar Webhook". Fornece o URL https desejado para receber webhooks e ativa o webhook para receber automaticamente atualizações de tarefas do Meshy. Podes 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 automaticamente enviadas para o URL de payload. Por razões de segurança, só permitimos o envio de webhooks para URLs https neste momento. Se quiseres configurar testes locais, vê a secção seguinte.

Requisitos de Entrega de Webhook

Para que o teu webhook funcione normalmente e continue a receber eventos:

  • O teu servidor deve 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.
  • Falhas consecutivas múltiplas podem:
    • Causar atrasos nas atualizações de progress ou chegarem fora de ordem
    • Desativar automaticamente o teu webhook após tentativas repetidas (ver Política de Desativação Automática)

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

Reencaminhamento de Webhooks para Testes Locais

Se quiseres testar o teu código de webhook localmente, que normalmente está num endereço http, podes usar uma URL de proxy de webhook para reencaminhar webhooks para o teu computador ou espaço de código. Abaixo estão os passos recomendados usando smee.io, mas podes usar qualquer serviço que queiras para gerar uma URL de proxy de webhook.

Obter uma URL de proxy de webhook:

  1. No teu navegador, navega para https://smee.io/
  2. Clica em "Start a new channel"
  3. Copia o URL completo em "Webhook Proxy URL". Irás usar este URL nos passos de configuração seguintes.

Reencaminhar webhooks:

  1. Se ainda não tens o smee-client instalado, executa o seguinte comando no teu terminal.
npm install --global smee-client
  1. Para receber webhooks reencaminhados do smee.io, executa o seguinte comando no teu terminal. Substitui WEBHOOK_PROXY_URL pelo teu URL de proxy de webhook de antes.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Deverás ver uma saída que se parece com isto, onde WEBHOOK_PROXY_URL é o teu URL de proxy de webhook:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Mantém isto a correr enquanto testas o teu webhook. Quando quiseres parar de reencaminhar webhooks, introduz Ctrl+C.
    Nota que o caminho é /webhook e a porta é 3000. Estes valores podem ser úteis quando quiseres configurar o teu próprio código para receber entregas de webhook mais tarde.

Criar um webhook:

Agora podes usar a 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, o Meshy enviará um payload de webhook 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 exemplos de payloads, vê: