Webhooks

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

Porque Criar Webhooks

Utilizar webhooks tem várias vantagens, especialmente no que diz respeito à verificação automática dos estados das tarefas da API. Os webhooks requerem menos esforço e custos do que estar constantemente a consultar (poll) a API para obter actualizações do estado das tarefas. Os webhooks também permitem actualizações quase em tempo real e, em última análise, escalam melhor do que a consulta contínua da API. Isto também lhe permite gerir melhor os seus limites de taxa, especialmente se estiver a consultar constantemente.

Configuração

Para activar os webhooks, abra a página de Webhooks na Plataforma de Programadores e clique no botão "Create Webhook". Forneça o URL https pretendido para receber webhooks e active o webhook para receber automaticamente actualizações de tarefas da Meshy. Pode ter no máximo 5 webhooks activos por conta Meshy. Quando um webhook está activado, todas as actualizações de estado das tarefas da API serão enviadas automaticamente para o URL de payload. Por motivos de segurança, apenas permitimos, de momento, 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 deve responder com um código de estado HTTP inferior a 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:
    • Causar atrasos nas actualizações de progress ou fazê-las chegar fora de ordem
    • Desactivar automaticamente o seu webhook após tentativas repetidas (ver Política de Desactivação Automática)

Sugestão: 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 código do seu webhook localmente, o que tipicamente corresponde a um endereço http, pode utilizar um URL de proxy de webhook para encaminhar os webhooks para o seu computador ou codespace. Os passos abaixo são recomendados utilizando o 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, navegue até https://smee.io/
  2. Clique em "Start a new channel"
  3. Copie o URL completo em "Webhook Proxy URL". Irá 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 a partir do smee.io, execute o seguinte comando no seu terminal. Substitua WEBHOOK_PROXY_URL pelo seu URL de proxy de webhook obtido anteriormente.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Deverá ver um resultado semelhante a este, onde 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, prima Ctrl+C.
    Note 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 webhooks mais tarde.

Criar um webhook:

Pode agora utilizar o URL de proxy de webhook para criar um novo webhook na página de Webhooks.

Resposta de Exemplo

Quando o estado de uma tarefa muda, a Meshy irá enviar (POST) um payload de webhook para o URL configurado. O payload contém o objecto da tarefa em formato JSON. Para uma descrição completa de todas as propriedades do objecto da tarefa e exemplos de payloads, consulte: