Webhooks

I Webhooks ti permettono di ricevere aggiornamenti in tempo reale da Meshy quando le tue attività API vengono completate o cambiano stato. Una volta configurati, Meshy invierà tramite POST i payload degli eventi in formato json agli URL che specifichi.

Perché Creare Webhooks

Usare i webhooks offre diversi vantaggi, specialmente per quanto riguarda il controllo automatico dello stato delle attività API. I webhooks richiedono meno sforzo e costi rispetto all'interrogazione continua dell'API per ottenere aggiornamenti sullo stato delle attività. I webhooks permettono inoltre aggiornamenti quasi in tempo reale e, in definitiva, si adattano meglio su larga scala rispetto al polling dell'API. Questo ti consente anche di gestire meglio i tuoi limiti di frequenza, specialmente se stai effettuando polling in modo costante.

Configurazione e Impostazione

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

Requisiti di Consegna dei 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 verrà considerata come una consegna fallita.
  • Più fallimenti consecutivi possono:
    • Causare ritardi negli aggiornamenti di progress o farli arrivare fuori ordine
    • Disabilitare automaticamente il tuo webhook dopo tentativi ripetuti (vedi la Policy di Disabilitazione Automatica)

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

Inoltro dei Webhooks per Test Locali

Se desideri testare il codice del tuo webhook localmente, che tipicamente si trova su un indirizzo http, puoi usare un URL proxy webhook per inoltrare i webhooks al tuo computer o codespace. Di seguito sono riportati i passaggi consigliati usando smee.io, ma puoi usare 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". Userai 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 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 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 tornarti utili quando vorrai configurare il tuo codice per ricevere le consegne dei webhook in seguito.

Crea 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'attività cambia, Meshy invierà tramite POST un payload webhook al tuo URL configurato. Il payload contiene l'oggetto dell'attività in formato JSON. Per una descrizione completa di tutte le proprietà dell'oggetto attività e degli esempi di payload, consulta: