Webhooks

Fai in modo che Meshy invii una richiesta POST al tuo server quando un task API fa progressi o termina, così non devi eseguire polling.

Perché usare i webhook

I webhook richiedono meno lavoro e costano meno rispetto al polling dell'API per lo stato di ogni task. Meshy invia ogni aggiornamento non appena avviene, quindi lo ricevi prima, e i webhook scalano meglio del polling. Invii anche meno richieste, il che ti mantiene più lontano dai tuoi rate limit.

Configurare un webhook

Per aggiungere un webhook, segui questi passaggi:

Apri la pagina Webhooks nella Developer Platform, e clicca su Create Webhook.
In Payload URL, inserisci l'URL che riceve le consegne. Meshy effettua le consegne solo tramite https://.
Seleziona Active, e clicca su Confirm.

Ogni account può avere 5 webhook attivi, e 10 in totale. Ogni webhook attivo riceve gli aggiornamenti di stato di tutti i tuoi task API.

Per testare un webhook con un server sul tuo computer, vedi Testare sul proprio computer.

Gestire una consegna

Per accettare una consegna, rispondi con uno stato inferiore a 400, ad esempio 200 o 202. Meshy attende circa 25 secondi per la risposta, quindi memorizza la consegna e rispondi prima. Esegui il lavoro più lento dopo, ad esempio il download del modello.

Uno stato pari o superiore a 400, oppure l'assenza di risposta, conta come consegna fallita. Meshy la ritenta con attese più lunghe tra i tentativi, fino a 4 volte per un aggiornamento IN_PROGRESS e fino a 9 volte per uno stato finale. Se 20 aggiornamenti consecutivi falliscono a ogni tentativo, Meshy può disattivare il webhook. Per riattivarlo, modificalo nella pagina Webhooks e seleziona Active.

Scrivi il tuo codice tenendo conto di questi casi:

Le consegne possono arrivare fuori ordine. Una consegna IN_PROGRESS può arrivare dopo quella finale, quindi non lasciare che sostituisca uno stato finale.
Lo stesso aggiornamento può arrivare più di una volta. Gestisci ogni coppia di id e status una sola volta.

Se la consegna finale di un task non è arrivata dopo circa il doppio del tempo tipico del task, recupera il task dal suo endpoint GET. Per i tempi tipici e quanto attendere, vedi Ciclo di vita del task.

Testare sul proprio computer

Meshy effettua le consegne solo verso un URL pubblico https://, quindi non può raggiungere direttamente un server sul tuo computer. Per testare il codice sul tuo computer, inoltra un URL pubblico ad esso con un proxy webhook. Questi passaggi usano smee.io, e qualsiasi servizio di proxy webhook funziona allo stesso modo.

Apri smee.io e clicca su Start a new channel. Copia l'URL sotto Webhook Proxy URL.
Se non hai ancora il client smee, installalo:
```
npm install --global smee-client
```
Inoltra il canale al tuo server. Sostituisci WEBHOOK_PROXY_URL con il tuo URL proxy webhook:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
L'output è simile a questo, dove WEBHOOK_PROXY_URL è il tuo URL proxy webhook:
```
Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
```
Lascialo in esecuzione mentre esegui i test. Per interrompere l'inoltro, premi Ctrl+C. Il tuo server riceve le consegne sulla porta 3000 al percorso /webhook, quindi configura il tuo codice per ascoltare lì.
Nella pagina Webhooks, crea un webhook con l'URL proxy webhook come Payload URL.

Payload di consegna

Meshy invia una consegna mentre un task è IN_PROGRESS, e un'altra quando il task raggiunge uno stato finale. Un task può raggiungere il suo stato finale senza una consegna IN_PROGRESS.

Ogni consegna è una richiesta POST al tuo URL payload con l'oggetto task come corpo JSON. È lo stesso oggetto restituito dall'endpoint GET del task, ad eccezione di progress. Una consegna invia progress con uno di questi valori:

50 mentre il task è IN_PROGRESS
100 quando il task ha successo
0 quando il task fallisce o viene annullato

Per i campi di ogni oggetto task, con un esempio, vedi le sezioni seguenti: