Webhooks

Met Webhooks kunt u realtime updates van Meshy ontvangen wanneer uw API-taken zijn voltooid of van status veranderen. Eenmaal geconfigureerd, zal Meshy event-payloads in JSON-formaat POSTen naar de URL's die u opgeeft.

Waarom Webhooks aanmaken

Het gebruik van webhooks biedt verschillende voordelen, vooral als het gaat om het automatisch controleren van API-taakstatussen. Webhooks vereisen minder moeite en kosten dan het continu pollen van de API om taakstatusupdates te krijgen. Webhooks maken ook bijna-realtime updates mogelijk en schalen uiteindelijk beter dan API-polling. Dit stelt u ook in staat om uw rate limits beter te beheren, vooral als u constant aan het pollen bent.

Instellen & Configuratie

Om webhooks in te schakelen, opent u de Webhooks-pagina in het Developer Platform en klikt u op de knop "Create Webhook". Geef de gewenste https-URL op waarnaar u webhooks wilt ontvangen en schakel de webhook in om automatisch taakupdates van Meshy te ontvangen. U kunt maximaal 5 actieve webhooks per Meshy-account hebben. Wanneer een webhook is ingeschakeld, worden alle API-taakstatusupdates automatisch naar de payload-URL gestuurd. Om veiligheidsredenen staan we op dit moment alleen toe om webhooks naar https-URL's te sturen. Als u lokaal testen wilt configureren, zie dan de volgende sectie.

Vereisten voor het afleveren van Webhooks

Om ervoor te zorgen dat uw webhook normaal functioneert en events blijft ontvangen:

  • Uw server moet reageren met een HTTP-statuscode lager dan 400 (bijv. 200 OK, 202 Accepted).
  • Elke reactie met een statuscode >= 400 wordt behandeld als een mislukte aflevering.
  • Meerdere opeenvolgende mislukkingen kunnen:
    • Ervoor zorgen dat progress-updates vertraagd of in de verkeerde volgorde binnenkomen
    • Uw webhook automatisch uitschakelen na herhaalde pogingen (zie Auto-Disable Policy)

Tip: Geef altijd een succesreactie terug nadat u de webhook-payload heeft gevalideerd en opgeslagen, zelfs als verdere verwerking asynchroon plaatsvindt.

Webhooks doorsturen voor lokaal testen

Als u uw webhook-code lokaal wilt testen, wat doorgaans op een http-adres is, kunt u een webhook-proxy-URL gebruiken om webhooks door te sturen naar uw computer of codespace. Hieronder volgen de aanbevolen stappen met behulp van smee.io, maar u kunt elke gewenste service gebruiken om een webhook-proxy-URL te genereren.

Verkrijg een webhook-proxy-URL:

  1. Navigeer in uw browser naar https://smee.io/
  2. Klik op "Start a new channel"
  3. Kopieer de volledige URL onder "Webhook Proxy URL". U gebruikt deze URL in de volgende installatiestappen.

Webhooks doorsturen:

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

U zou een uitvoer moeten zien die er ongeveer zo uitziet, waarbij WEBHOOK_PROXY_URL uw webhook-proxy-URL is:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Laat dit actief terwijl u uw webhook test. Wanneer u wilt stoppen met het doorsturen van webhooks, drukt u op Ctrl+C.
    Merk op dat het pad /webhook is en de poort 3000. Deze waarden kunnen van pas komen wanneer u later uw eigen code wilt opzetten om webhook-afleveringen te ontvangen.

Maak een webhook aan:

U kunt nu de webhook-proxy-URL gebruiken om een nieuwe webhook aan te maken op de Webhooks-pagina.

Voorbeeldreactie

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