Webhooks

I Webhooks ti consentono di ricevere aggiornamenti in tempo reale da Meshy quando le tue attività API vengono completate o cambiano stato. Una volta configurato, Meshy invierà tramite POST payload di eventi in formato json agli URL specificati.

Perché creare Webhooks

L'utilizzo dei webhook presenta diversi vantaggi, soprattutto per quanto riguarda il controllo automatico degli stati delle attività API. I Webhooks richiedono meno impegno e costi rispetto al polling continuo dell'API per ottenere aggiornamenti sullo stato delle attività. I Webhooks 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 frequenza, soprattutto se esegui polling costantemente.

Configurazione e impostazione

Per abilitare i webhook, vai alla pagina delle impostazioni API quando hai effettuato l'accesso all'applicazione web Meshy. Trova la sezione "Webhooks" sotto le tue chiavi API e fai clic sul pulsante "Crea Webhook". Fornisci l'URL https desiderato da cui ricevere i webhook e abilita il webhook per ricevere automaticamente aggiornamenti sulle attività da Meshy. Puoi avere un massimo di 5 webhook attivi per account Meshy. Quando un webhook è abilitato, tutti gli aggiornamenti dello stato delle attività API verranno inviati automaticamente all'URL payload. Per motivi di sicurezza, al momento consentiamo l'invio di webhook 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 esempio, 200 OK, 202 Accepted).
  • Qualsiasi risposta con un codice di stato >= 400 verrà considerata una consegna non riuscita.
  • Più errori consecutivi possono:
    • Causare ritardi negli aggiornamenti di progress o farli arrivare fuori ordine
    • Disabilitare automaticamente il tuo webhook dopo tentativi ripetuti (vedi Criterio di disabilitazione automatica)

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

Inoltro dei Webhooks per test locali

Se desideri testare localmente il codice del tuo webhook, che in genere 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.

Ottieni un URL proxy webhook:

  1. Nel browser, vai a https://smee.io/
  2. Fai clic su "Avvia un nuovo canale"
  3. Copia l'URL completo sotto "URL proxy webhook". Userai questo URL nei passaggi di configurazione seguenti.

Inoltra i webhook:

  1. Se non hai già installato smee-client, esegui il seguente comando nel terminale.
npm install --global smee-client
  1. Per ricevere i webhook inoltrati da smee.io, esegui il seguente comando nel terminale. Sostituisci WEBHOOK_PROXY_URL con il tuo URL proxy webhook di prima.
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, inserisci Ctrl+C.
    Nota che il percorso è /webhook e la porta è 3000. Questi valori possono tornare utili quando vorrai configurare il tuo codice per ricevere consegne webhook in seguito.

Crea un webhook:

Ora puoi usare l'URL proxy webhook per creare un nuovo webhook nella pagina delle impostazioni di Meshy API.

Risposta di esempio

Quando lo stato di un'attività cambia, Meshy invierà tramite POST un payload webhook al tuo URL configurato. Il payload contiene l'oggetto attività in formato JSON. Per una descrizione completa di tutte le proprietà dell'oggetto attività e payload di esempio, consulta: