Webhooks

Faça com que a Meshy envie um pedido POST para o seu servidor quando uma tarefa da API progride ou termina, para que não precise de fazer polling.

Porquê usar webhooks

Os webhooks exigem menos trabalho e custam menos do que fazer polling à API para verificar o estado de cada tarefa. A Meshy envia cada atualização assim que ocorre, pelo que a recebe mais cedo, e os webhooks escalam melhor do que o polling. Além disso, envia menos pedidos, o que o mantém mais afastado dos seus limites de taxa.

Configurar um webhook

Para adicionar um webhook, siga estes passos:

Abra a página de Webhooks na Plataforma de Programadores e clique em Create Webhook.
Em Payload URL, introduza o URL que recebe as entregas. A Meshy só entrega através de https://.
Guarde uma cópia do Webhook Secret que a caixa de diálogo preenche. Todas as entregas o incluem, para que o seu servidor possa verificar que um pedido veio da Meshy. Para um webhook que já possui, clique no ícone do olho na coluna Secret para o ver.
Selecione Active e clique em Confirm.

Cada conta pode ter 5 webhooks ativos, e 10 no total. Todos os webhooks ativos recebem as atualizações de estado de todas as suas tarefas da API.

Para testar um webhook com um servidor no seu computador, consulte Testar no seu computador.

Processar uma entrega

Para aceitar uma entrega, responda com um estado abaixo de 400, como 200 ou 202. A Meshy aguarda cerca de 25 segundos pela resposta, pelo que deve armazenar a entrega e responder primeiro. Faça o trabalho mais demorado depois disso, como transferir o modelo.

Um estado igual ou superior a 400, ou a ausência de resposta, conta como uma entrega falhada. A Meshy tenta novamente com intervalos de espera mais longos entre tentativas, até 4 vezes para uma atualização IN_PROGRESS e até 9 vezes para um estado final. Se 20 atualizações consecutivas falharem em todas as tentativas, a Meshy pode desativar o webhook. Para o reativar, edite-o na página de Webhooks e selecione Active.

Escreva o seu código tendo em conta estes casos:

As entregas podem chegar fora de ordem. Uma entrega IN_PROGRESS pode chegar depois da final, portanto não deixe que substitua um estado final.
A mesma atualização pode chegar mais do que uma vez. Processe cada par de id e status apenas uma vez.
Qualquer pessoa que conheça o seu URL pode enviar-lhe um pedido. Compare X-MESHY-API-WEBHOOK-SECRET-KEY com a sua cópia do segredo, e rejeite um pedido que não corresponda.

Se a entrega final de uma tarefa não tiver chegado após cerca do dobro do tempo típico da tarefa, obtenha a tarefa através do seu endpoint GET. Para tempos típicos e quanto tempo esperar, consulte Ciclo de vida da tarefa.

Testar no seu computador

A Meshy só entrega a um URL público https://, pelo que não consegue chegar diretamente a um servidor no seu computador. Para testar código no seu computador, encaminhe um URL público 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 o URL em Webhook Proxy URL.
Se ainda não tiver o cliente smee, instale-o:
```
npm install --global smee-client
```
Encaminhe o canal para o seu servidor. Substitua WEBHOOK_PROXY_URL pelo seu URL de proxy de webhook:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
A saída será semelhante a esta, 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
```
Mantenha-o em execução enquanto testa. Para parar o encaminhamento, prima Ctrl+C. O seu servidor recebe as entregas na porta 3000 no caminho /webhook, pelo que deve configurar o seu código para escutar aí.
Na página de Webhooks, crie um webhook com o URL de proxy de webhook como o seu Payload URL.

Payload de entrega

A Meshy envia uma entrega enquanto uma tarefa está IN_PROGRESS, e outra quando a tarefa atinge um estado final. Uma tarefa pode atingir o seu estado final sem uma entrega IN_PROGRESS.

Cada entrega é um POST para o seu URL de payload com os seguintes cabeçalhos:

Cabeçalho	Valor
`X-MESHY-API-WEBHOOK-SECRET-KEY`	O segredo do webhook
`X-MESHY-API-WEBHOOK-USER-ID`	O ID do utilizador Meshy proprietário 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 devolve, exceto progress. Uma entrega envia progress como um dos seguintes valores:

50 enquanto a tarefa está IN_PROGRESS
100 quando a tarefa é concluída com sucesso
0 quando a tarefa falha ou é cancelada

Para os campos de cada objeto de tarefa, com um exemplo, consulte as seguintes secções: