Webhooks
Faça o Meshy enviar uma requisição POST ao seu servidor quando uma tarefa da API avançar ou terminar, para que você não precise fazer polling.
Por que usar webhooks
Webhooks dão menos trabalho e custam menos do que fazer polling da API para verificar o status de cada tarefa. O Meshy envia cada atualização assim que ela acontece, então você a recebe mais rápido, e webhooks escalam melhor do que polling. Você também envia menos requisições, o que o mantém mais longe dos seus limites de taxa.
Configurar um webhook
Para adicionar um webhook, siga estes passos:
- Abra a página de Webhooks na Plataforma do Desenvolvedor e clique em Create Webhook.
- Em Payload URL, informe a URL que receberá as entregas. O Meshy entrega apenas via
https://. - Guarde uma cópia do Webhook Secret que a caixa de diálogo preenche. Toda entrega o carrega, para que seu servidor possa verificar que a requisição veio do Meshy. Para um webhook que você já tem, clique no ícone de olho na coluna Secret para vê-lo.
- Selecione Active e clique em Confirm.
Cada conta pode ter 5 webhooks ativos, e 10 no total. Todo webhook ativo recebe as atualizações de status de todas as suas tarefas da API.
Para testar um webhook com um servidor no seu computador, veja Testar no seu computador.
Processar uma entrega
Para aceitar uma entrega, responda com um status abaixo de 400, como 200 ou 202. O Meshy aguarda cerca de 25 segundos pela resposta, então armazene a entrega e responda primeiro. Faça o trabalho mais demorado depois disso, como baixar o modelo.
Um status 400 ou acima, ou a ausência de resposta, conta como uma entrega falha. O Meshy tenta novamente com esperas cada vez maiores entre as tentativas, até 4 vezes para uma atualização IN_PROGRESS e até 9 vezes para um status final. Se 20 atualizações seguidas falharem em todas as tentativas, o Meshy pode desativar o webhook. Para reativá-lo, edite-o na página de Webhooks e selecione Active.
Escreva seu código para estes casos:
- As entregas podem chegar fora de ordem. Uma entrega
IN_PROGRESSpode chegar depois da final, então não deixe que ela substitua um status final. - A mesma atualização pode chegar mais de uma vez. Processe cada par de
idestatusuma única vez. - Qualquer pessoa que souber sua URL pode enviar uma requisição a ela. Compare
X-MESHY-API-WEBHOOK-SECRET-KEYcom a sua cópia do secret e rejeite uma requisição que não corresponda.
Se a entrega final de uma tarefa não chegou depois de aproximadamente o dobro do tempo típico da tarefa, obtenha a tarefa pelo seu endpoint GET. Para tempos típicos e quanto esperar, veja Ciclo de vida da tarefa.
Testar no seu computador
O Meshy entrega apenas para uma URL pública https://, então ele não consegue alcançar diretamente um servidor no seu computador. Para testar código no seu computador, encaminhe uma URL pública para ele com um proxy de webhook. Estes passos usam o smee.io, e qualquer serviço de proxy de webhook funciona da mesma forma.
-
Abra o smee.io e clique em Start a new channel. Copie a URL em Webhook Proxy URL.
-
Se você ainda não tem o cliente smee, instale-o:
npm install --global smee-client -
Encaminhe o canal para o seu servidor. Substitua
WEBHOOK_PROXY_URLpela sua URL de proxy de webhook:smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000A saída será parecida com esta, em que
WEBHOOK_PROXY_URLé a sua URL de proxy de webhook:Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook Connected WEBHOOK_PROXY_URLMantenha-o em execução enquanto testa. Para parar o encaminhamento, pressione Ctrl+C. Seu servidor recebe as entregas na porta
3000no caminho/webhook, então configure seu código para escutar ali. -
Na página de Webhooks, crie um webhook com a URL de proxy de webhook como sua Payload URL.
Payload de entrega
O Meshy envia uma entrega enquanto uma tarefa está IN_PROGRESS, e outra quando a tarefa chega a um status final. Uma tarefa pode chegar ao seu status final sem uma entrega IN_PROGRESS.
Cada entrega é um POST para a sua URL de payload com estes cabeçalhos:
| Cabeçalho | Valor |
|---|---|
X-MESHY-API-WEBHOOK-SECRET-KEY | O secret do webhook |
X-MESHY-API-WEBHOOK-USER-ID | O ID do usuário do Meshy dono do webhook |
Meshy-Webhook-Version | v1, o formato do corpo |
Content-Type | application/json |
User-Agent | MeshyAPIWebhook/1.0.0 |
O corpo JSON é o objeto da tarefa. É o mesmo objeto que o endpoint GET da tarefa retorna, exceto progress. Uma entrega envia progress como um destes valores:
50enquanto a tarefa estáIN_PROGRESS100quando a tarefa é bem-sucedida0quando a tarefa falha ou é cancelada
Para os campos de cada objeto de tarefa, com um exemplo, veja as seções a seguir: