lowpoly wordt op 30 okt 2026 uitgefaseerd. Stap vóór deze datums over op een ander model om fouten bij verzoeken te voorkomen.

Webhooks

Met Webhooks ontvang je realtime updates van Meshy wanneer je API-taken zijn voltooid of van status veranderen. Zodra ze zijn geconfigureerd, stuurt Meshy event-payloads in JSON-formaat via POST naar de URL's die je opgeeft.

Waarom Webhooks maken

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 statusupdates van taken te verkrijgen. Webhooks maken ook bijna-realtime updates mogelijk en schalen uiteindelijk beter dan API-polling. Dit stelt je ook in staat om je rate limits beter te beheren, vooral als je voortdurend aan het pollen bent.

Installatie & Configuratie

Om webhooks in te schakelen, open je de Webhooks-pagina in het Developer Platform en klik je op de knop "Create Webhook". Geef de gewenste https-URL op waarop je webhooks wilt 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 webhookbezorging

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

  • Je server moet antwoorden met een HTTP-statuscode lager dan 400 (bijv. 200 OK, 202 Accepted).
  • Elke respons met een statuscode >= 400 wordt beschouwd als een mislukte bezorging.
  • Meerdere opeenvolgende mislukkingen kunnen:
    • Ertoe leiden dat progress-updates vertraagd of in de verkeerde volgorde aankomen
    • Je webhook automatisch uitschakelen na herhaalde pogingen (zie Auto-Disable Policy)

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

Als het laatste event van een taak niet is binnengekomen na ongeveer het dubbele van de gebruikelijke tijd, haal de taak dan op via het bijbehorende GET-endpoint. Zie Task Lifecycle voor gebruikelijke tijden en hoe lang je moet wachten.

Webhooks doorsturen voor lokaal testen

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

Een webhook-proxy-URL verkrijgen:

  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 gebruikt deze URL in de volgende installatiestappen.

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 webhook-proxy-URL van eerder.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Je zou output moeten zien die er zo 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, druk je op Ctrl+C.
    Let op dat het pad /webhook is en de poort 3000. Deze waarden kunnen later van pas komen wanneer je je eigen code wilt opzetten om webhookbezorgingen te ontvangen.

Een webhook maken:

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

Voorbeeldrespons

Wanneer de status van een taak verandert, stuurt Meshy via POST een webhook-payload naar de door jou geconfigureerde URL. De payload bevat het taakobject in JSON-formaat. Voor een volledige beschrijving van alle eigenschappen van het taakobject en voorbeeldpayloads, zie: