Webhooks

I Webhooks ti permettono di ricevere aggiornamenti in tempo reale da Meshy quando i tuoi compiti API sono completati o cambiano stato. Una volta configurati, Meshy invierà i payload degli eventi in formato json agli URL che specifichi.

Perché Creare Webhooks

L'uso dei webhooks ha diversi vantaggi, specialmente per quanto riguarda il controllo automatico degli stati dei compiti API. I Webhooks richiedono meno sforzo e costi rispetto al polling continuo dell'API per ottenere aggiornamenti sullo stato dei compiti. I Webhooks permettono anche aggiornamenti quasi in tempo reale e, in definitiva, scalano meglio del polling API. Questo ti consente anche di gestire meglio i tuoi limiti di velocità, specialmente se stai effettuando polling costantemente.

Configurazione e Impostazione

Per abilitare i webhooks, naviga alla pagina delle impostazioni API quando sei loggato nell'applicazione web di Meshy. Trova la sezione "Webhooks" sotto le tue API Keys e clicca sul pulsante "Crea Webhook". Fornisci il tuo URL https desiderato per ricevere i webhooks e abilita il webhook per ricevere automaticamente gli aggiornamenti dei compiti da Meshy. Puoi avere un massimo di 5 webhooks attivi per account Meshy. Quando un webhook è abilitato, tutti gli aggiornamenti di stato dei compiti API saranno inviati automaticamente all'URL payload. Per motivi di sicurezza, al momento consentiamo l'invio di webhooks solo a URL https. Se desideri configurare test locali, consulta la sezione seguente.

Requisiti di Consegna del Webhook

Affinché il tuo webhook funzioni normalmente e continui a ricevere eventi:

  • Il tuo server deve rispondere con un codice di stato HTTP inferiore a 400 (ad es., 200 OK, 202 Accepted).
  • Qualsiasi risposta con un codice di stato >= 400 sarà trattata come una consegna fallita.
  • Fallimenti consecutivi multipli possono:
    • Causare ritardi negli aggiornamenti di progress o arrivi fuori ordine
    • Disabilitare automaticamente il tuo webhook dopo tentativi ripetuti (vedi Politica di Disabilitazione Automatica)

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

Inoltro dei Webhooks per Test Locali

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

Ottieni 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 seguenti.

Inoltra i webhooks:

  1. Se non hai già installato smee-client, esegui il seguente comando nel tuo terminale.
npm install --global smee-client
  1. Per ricevere i webhooks 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. Tieni questo in esecuzione mentre testi il tuo webhook. Quando vuoi interrompere l'inoltro dei webhooks, premi Ctrl+C.
    Nota che il percorso è /webhook e la porta è 3000. Questi valori potrebbero tornare utili quando desideri configurare il tuo codice per ricevere le consegne dei webhooks in seguito.

Crea un webhook:

Puoi ora utilizzare l'URL proxy webhook per creare un nuovo webhook nella pagina delle impostazioni API di Meshy.

Risposta di Esempio

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