lowpoly verrà ritirato il 30 ott 2026. Cambia modello prima di queste date per evitare errori nelle richieste.

Webhooks

I Webhooks ti permettono di ricevere aggiornamenti in tempo reale da Meshy quando i tuoi task API vengono completati o cambiano stato. Una volta configurati, Meshy invierà tramite POST i payload degli eventi in formato json agli URL specificati.

Perché creare Webhooks

Utilizzare i webhook offre numerosi vantaggi, specialmente per quanto riguarda il controllo automatico dello stato dei task API. I webhook richiedono meno impegno e costi rispetto all'interrogazione continua (polling) dell'API per ottenere aggiornamenti sullo stato dei task. I webhook consentono inoltre aggiornamenti quasi in tempo reale e, in definitiva, scalano meglio rispetto al polling dell'API. Questo ti permette anche di gestire meglio i tuoi limiti di velocità (rate limit), specialmente se effettui polling in modo costante.

Configurazione e impostazione

Per abilitare i webhook, apri la pagina Webhooks nella Developer Platform e clicca sul pulsante "Create Webhook". Fornisci l'URL https desiderato per ricevere i webhook e abilita il webhook per ricevere automaticamente gli aggiornamenti dei task da Meshy. Puoi avere un massimo di 5 webhook attivi per ogni account Meshy. Quando un webhook è abilitato, tutti gli aggiornamenti di stato dei task API verranno automaticamente inviati all'URL payload. Per motivi di sicurezza, al momento consentiamo l'invio di webhook solo verso URL https. Se desideri configurare i test in locale, consulta la sezione seguente.

Requisiti di consegna dei Webhook

Perché il tuo webhook funzioni correttamente e continui a ricevere eventi:

  • Il tuo server deve rispondere con un codice di stato HTTP inferiore a 400 (ad esempio, 200 OK, 202 Accepted).
  • Qualsiasi risposta con un codice di stato >= 400 verrà considerata come una consegna non riuscita.
  • Più fallimenti consecutivi possono:
    • Causare ritardi negli aggiornamenti del progress o il loro arrivo in ordine non corretto
    • Disabilitare automaticamente il tuo webhook dopo tentativi ripetuti (consulta la Politica di disabilitazione automatica)

Suggerimento: Restituisci sempre una risposta di successo dopo aver validato e memorizzato il payload del webhook, anche se l'elaborazione successiva avviene in modo asincrono.

Se l'evento finale di un task non arriva dopo circa il doppio del suo tempo tipico, recupera il task tramite il suo endpoint GET. Consulta Ciclo di vita del task per i tempi tipici e quanto attendere.

Inoltro dei Webhooks per i test in locale

Se desideri testare il tuo codice webhook in locale, che tipicamente si trova a un indirizzo http, puoi usare un URL proxy webhook per inoltrare i webhook al tuo computer o codespace. Di seguito sono riportati i passaggi consigliati utilizzando smee.io, ma puoi usare qualsiasi servizio desideri per generare un URL proxy webhook.

Ottenere un URL proxy webhook:

  1. Nel tuo browser, naviga su https://smee.io/
  2. Clicca su "Start a new channel"
  3. Copia l'URL completo sotto "Webhook Proxy URL". Utilizzerai questo URL nei passaggi di configurazione successivi.

Inoltrare i webhook:

  1. Se non hai già installato smee-client, esegui il seguente comando nel tuo terminale.
npm install --global smee-client
  1. Per ricevere i webhook inoltrati da smee.io, esegui il seguente comando nel tuo terminale. Sostituisci WEBHOOK_PROXY_URL con il tuo URL proxy webhook ottenuto in precedenza.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Dovresti vedere un 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
  1. Mantieni questo processo in esecuzione mentre testi il tuo webhook. Quando vuoi interrompere l'inoltro dei webhook, premi Ctrl+C.
    Nota che il percorso è /webhook e la porta è 3000. Questi valori potrebbero essere utili quando vorrai configurare il tuo codice per ricevere le consegne dei webhook in futuro.

Creare un webhook:

Ora puoi usare l'URL proxy webhook per creare un nuovo webhook sulla pagina Webhooks.

Esempio di risposta

Quando lo stato di un task cambia, Meshy invierà tramite POST un payload webhook all'URL che hai configurato. Il payload contiene l'oggetto task in formato JSON. Per una descrizione completa di tutte le proprietà dell'oggetto task e degli esempi di payload, consulta: