Webhooks
Fai in modo che Meshy invii una richiesta POST al tuo server quando un task API fa progressi o termina, così non devi fare 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. Inoltre invii meno richieste, il che ti mantiene più lontano dai tuoi limiti di frequenza.
Configurare un webhook
Per aggiungere un webhook, segui questi passaggi:
- Apri la pagina Webhooks nella Developer Platform e fai clic su Create Webhook.
- In Payload URL, inserisci l'URL che riceve le consegne. Meshy effettua le consegne solo tramite
https://. - Conserva una copia del Webhook Secret che la finestra di dialogo compila automaticamente. Ogni consegna lo include, in modo che il tuo server possa verificare che una richiesta provenga da Meshy. Per un webhook che hai già creato, fai clic sull'icona a forma di occhio nella colonna Secret per visualizzarlo.
- Seleziona Active e fai clic 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, consulta Testare sul proprio computer.
Gestire una consegna
Per accettare una consegna, rispondi con uno stato inferiore a 400, come 200 o 202. Meshy attende circa 25 secondi per la risposta, quindi memorizza prima la consegna e rispondi subito dopo. Svolgi il lavoro più lento in seguito, ad esempio il download del modello.
Uno stato pari o superiore a 400, o l'assenza di risposta, viene considerato come una consegna fallita. Meshy la ripete con attese più lunghe tra un tentativo e l'altro, 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_PROGRESSpuò 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
idestatusuna sola volta. - Chiunque conosca il tuo URL può inviargli una richiesta. Confronta
X-MESHY-API-WEBHOOK-SECRET-KEYcon la tua copia del secret e rifiuta una richiesta che non corrisponde.
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, consulta Ciclo di vita del task.
Testare sul proprio computer
Meshy effettua 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 verso di esso con un proxy webhook. Questi passaggi usano smee.io, e qualsiasi servizio di proxy webhook funziona allo stesso modo.
-
Apri smee.io e fai clic 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_URLcon il tuo URL proxy webhook:smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000L'output ha questo aspetto, dove
WEBHOOK_PROXY_URLè il tuo URL proxy webhook:Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook Connected WEBHOOK_PROXY_URLLascialo in esecuzione durante il test. Per interrompere l'inoltro, premi Ctrl+C. Il tuo server riceve le consegne sulla porta
3000al percorso/webhook, quindi configura il tuo codice per rimanere in ascolto 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 questi header:
| Header | Valore |
|---|---|
X-MESHY-API-WEBHOOK-SECRET-KEY | Il secret del webhook |
X-MESHY-API-WEBHOOK-USER-ID | L'ID dell'utente Meshy proprietario del webhook |
Meshy-Webhook-Version | v1, il formato del corpo |
Content-Type | application/json |
User-Agent | MeshyAPIWebhook/1.0.0 |
Il corpo JSON è l'oggetto task. È lo stesso oggetto restituito dall'endpoint GET del task, ad eccezione di progress. Una consegna invia progress come uno di questi valori:
50mentre il task èIN_PROGRESS100quando il task ha successo0quando il task fallisce o viene annullato
Per i campi di ogni oggetto task, con un esempio, consulta le sezioni seguenti: