Webhooks

Met Webhooks kun je realtime updates van Meshy ontvangen wanneer je API-taken zijn voltooid of van status veranderen. Zodra dit is geconfigureerd, zal Meshy event-payloads in json-formaat via POST versturen naar de URL's die je opgeeft.

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 verkrijgen. Webhooks maken ook bijna realtime updates mogelijk en schalen uiteindelijk beter dan API-polling. Hierdoor kun je ook je rate limits beter beheren, vooral als je voortdurend pollt.

Installatie & configuratie

Om webhooks in te schakelen, navigeer je naar de pagina met API-instellingen wanneer je bent ingelogd bij 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 te ontvangen en schakel de webhook in om automatisch taakupdates van Meshy te ontvangen. Je kunt maximaal 5 actieve webhooks per Meshy-account hebben. Wanneer een webhook is ingeschakeld, worden alle statusupdates van API-taken automatisch naar de payload-URL verzonden. Om veiligheidsredenen staan we momenteel alleen toe dat webhooks naar https-URL's worden verzonden. Als je lokaal testen wilt configureren, zie dan de volgende sectie.

Vereisten voor Webhook-levering

Om je webhook normaal te laten functioneren en events te blijven ontvangen:

  • Je server moet reageren met een HTTP-statuscode lager dan 400 (bijv. 200 OK, 202 Accepted).
  • Elke respons met een statuscode >= 400 wordt behandeld als een mislukte levering.
  • Meerdere opeenvolgende fouten kunnen:
    • Ervoor zorgen dat progress-updates worden vertraagd of niet in de juiste volgorde aankomen
    • Je webhook automatisch uitschakelen na herhaalde pogingen (zie Beleid voor automatisch uitschakelen)

Tip: Stuur altijd een succesrespons terug nadat je de webhook-payload hebt gevalideerd en opgeslagen, zelfs als verdere verwerking asynchroon plaatsvindt.

Webhooks doorsturen voor lokaal 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 door te sturen naar je computer of codespace. Hieronder staan aanbevolen stappen met smee.io, maar je kunt elke gewenste service gebruiken om een webhook-proxy-URL te genereren.

Een webhook-proxy-URL ophalen:

  1. Navigeer in je browser naar https://smee.io/
  2. Klik op "Een nieuw kanaal starten"
  3. Kopieer de volledige URL onder "webhook-proxy-URL". Je gebruikt deze URL in de volgende installatiestappen.

Webhooks doorsturen:

  1. Als je smee-client nog niet hebt geïnstalleerd, voer je 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 webhook-proxy-URL van eerder.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Je zou uitvoer 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. Laat dit draaien terwijl je je webhook test. Wanneer je wilt stoppen met het doorsturen van webhooks, voer je Ctrl+C in.
    Merk op dat het pad /webhook is en de poort 3000. Deze waarden kunnen van pas komen wanneer je later je eigen code wilt instellen om webhook-leveringen te ontvangen.

Een webhook maken:

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

Voorbeeldrespons

Wanneer de status van een taak verandert, zal Meshy een webhook-payload via POST naar je geconfigureerde URL sturen. De payload bevat het taakobject in JSON-formaat. Voor een volledige beschrijving van alle eigenschappen van het taakobject en voorbeeld-payloads, zie: