Webhooks

Webhooks stellen je in staat om real-time updates van Meshy te ontvangen wanneer je API-taken zijn voltooid of van status veranderen. Eenmaal geconfigureerd, zal Meshy gebeurtenis-payloads in json-formaat naar de door jou opgegeven URL's POSTen.

Waarom Webhooks Maken

Het gebruik van webhooks heeft verschillende voordelen, vooral met betrekking tot het automatisch controleren van API-taakstatussen. Webhooks vereisen minder inspanning en kosten dan het continu pollen van de API om taakstatusupdates te krijgen. Webhooks bieden ook bijna real-time updates en schalen uiteindelijk beter dan API-polling. Dit stelt je ook in staat om je snelheidslimieten beter te beheren, vooral als je constant aan het pollen bent.

Setup & Configuratie

Om webhooks in te schakelen, navigeer je naar de API-instellingenpagina wanneer je bent ingelogd op de Meshy-webapplicatie. Zoek de sectie "Webhooks" onder je API Keys en klik op de knop "Webhook Maken". Geef je gewenste https-URL op om webhooks van te ontvangen en schakel de webhook in om automatisch taakupdates van Meshy te ontvangen. Je mag maximaal 5 actieve webhooks per Meshy-account hebben. Wanneer een webhook is ingeschakeld, worden alle API-taakstatusupdates automatisch naar de payload-URL verzonden. Om veiligheidsredenen staan we op dit moment alleen het verzenden van webhooks naar https-URL's toe. Als je lokale testen wilt configureren, zie het volgende gedeelte.

Webhook Leveringseisen

Voor je webhook om normaal te functioneren en evenementen te blijven ontvangen:

  • Je server moet reageren met een HTTP-statuscode onder 400 (bijv. 200 OK, 202 Accepted).
  • Elke reactie met een statuscode >= 400 wordt behandeld als een mislukte levering.
  • Meerdere opeenvolgende mislukkingen kunnen:
    • Veroorzaken dat progress-updates worden vertraagd of in de verkeerde volgorde aankomen
    • Automatisch je webhook uitschakelen na herhaalde pogingen (zie Auto-Uitschakelbeleid)

Tip: Geef altijd een succesvolle reactie nadat je de webhook-payload hebt gevalideerd en opgeslagen, zelfs als verdere verwerking asynchroon plaatsvindt.

Webhooks Doorsturen voor Lokale Testen

Als je je webhook-code lokaal wilt testen, wat meestal op een http-adres is, kun je een webhook-proxy-URL gebruiken om webhooks naar je computer of codespace door te sturen. Hieronder staan aanbevolen stappen met smee.io, maar je kunt elke dienst gebruiken die je wilt om een webhook-proxy-URL te genereren.

Verkrijg een webhook-proxy-URL:

  1. Navigeer in je browser naar https://smee.io/
  2. Klik op "Start a new channel"
  3. Kopieer de volledige URL onder "Webhook Proxy URL". Je zult deze URL gebruiken in de volgende setup-stappen.

Webhooks doorsturen:

  1. Als je smee-client nog niet hebt geïnstalleerd, voer dan de volgende opdracht uit in je terminal.
npm install --global smee-client
  1. Om doorgestuurde webhooks van smee.io te ontvangen, voer je de volgende opdracht uit in je terminal. Vervang WEBHOOK_PROXY_URL door je eerder verkregen webhook-proxy-URL.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Je zou een output moeten zien die er als volgt uitziet, waarbij WEBHOOK_PROXY_URL je webhook-proxy-URL is:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Houd dit draaiende terwijl je je webhook test. Wanneer je wilt stoppen met het doorsturen van webhooks, voer je Ctrl+C in.
    Let op dat het pad /webhook is en de poort 3000. Deze waarden kunnen handig zijn wanneer je later je eigen code wilt instellen om webhook-leveringen te ontvangen.

Maak een webhook:

Je kunt nu de webhook-proxy-URL gebruiken om een nieuwe webhook te maken op de Meshy API-instellingenpagina.

Voorbeeldreactie

Wanneer een taakstatus verandert, zal Meshy een webhook-payload naar je geconfigureerde URL POSTen. De payload bevat het taakobject in JSON-formaat. Voor een volledige beschrijving van alle taakobjecteigenschappen en voorbeeldpayloads, zie: