Webhooks

Laat Meshy een POST-verzoek naar je server sturen wanneer een API-taak voortgang boekt of voltooid is, zodat je niet hoeft te pollen.

Waarom webhooks gebruiken

Webhooks kosten minder werk en minder geld dan het pollen van de API voor de status van elke taak. Meshy stuurt elke update zodra deze zich voordoet, zodat je deze eerder ontvangt, en webhooks schalen beter dan polling. Je verstuurt ook minder verzoeken, waardoor je verder van je rate limits blijft.

Een webhook instellen

Volg deze stappen om een webhook toe te voegen:

Open de Webhooks-pagina in het Developer Platform en klik op Create Webhook.
Voer bij Payload URL de URL in die de deliveries ontvangt. Meshy levert alleen via https://.
Bewaar een kopie van het Webhook Secret dat het dialoogvenster invult. Elke delivery bevat dit, zodat je server kan controleren of een verzoek van Meshy afkomstig is. Voor een webhook die je al hebt, klik je op het oogpictogram in de kolom Secret om deze te bekijken.
Selecteer Active en klik op Confirm.

Elk account kan 5 actieve webhooks hebben, en 10 in totaal. Elke actieve webhook ontvangt de statusupdates van al je API-taken.

Zie Testen op je computer om een webhook te testen met een server op je computer.

Een delivery afhandelen

Reageer met een status lager dan 400, zoals 200 of 202, om een delivery te accepteren. Meshy wacht ongeveer 25 seconden op de respons, dus sla de delivery eerst op en reageer daarna. Doe het trage werk daarna, zoals het downloaden van het model.

Een status van 400 of hoger, of geen respons, telt als een mislukte delivery. Meshy probeert het opnieuw met langere wachttijden tussen pogingen, tot 4 keer voor een IN_PROGRESS-update en tot 9 keer voor een definitieve status. Als 20 updates op rij bij elke poging mislukken, kan Meshy de webhook deactiveren. Om deze weer in te schakelen, bewerk je hem op de Webhooks-pagina en selecteer je Active.

Schrijf je code voor deze gevallen:

Deliveries kunnen in de verkeerde volgorde aankomen. Een IN_PROGRESS-delivery kan na de definitieve aankomen, dus laat deze geen definitieve status vervangen.
Dezelfde update kan meer dan eens aankomen. Verwerk elk paar van id en status eenmalig.
Iedereen die je URL kent, kan er een verzoek naartoe sturen. Vergelijk X-MESHY-API-WEBHOOK-SECRET-KEY met je kopie van het secret en wijs een verzoek af dat niet overeenkomt.

Als de definitieve delivery van een taak niet is aangekomen na ongeveer het dubbele van de gebruikelijke duur van de taak, haal de taak dan op via het GET-endpoint. Zie Task lifecycle voor gebruikelijke tijden en hoe lang je moet wachten.

Testen op je computer

Meshy levert alleen aan een publieke https://-URL en kan daarom een server op je computer niet rechtstreeks bereiken. Om code op je computer te testen, stuur je met een webhook-proxy een publieke URL ernaartoe door. Deze stappen gebruiken smee.io, en elke webhook-proxyservice werkt op dezelfde manier.

Open smee.io en klik op Start a new channel. Kopieer de URL onder Webhook Proxy URL.
Als je de smee-client nog niet hebt, installeer je deze:
```
npm install --global smee-client
```
Stuur het kanaal door naar je server. Vervang WEBHOOK_PROXY_URL door je webhook-proxy-URL:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
De uitvoer ziet er als volgt uit, 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
```
Laat dit actief terwijl je test. Druk op Ctrl+C om het doorsturen te stoppen. Je server ontvangt de deliveries op poort 3000 op het pad /webhook, dus stel je code in om daar te luisteren.
Maak op de Webhooks-pagina een webhook aan met de webhook-proxy-URL als Payload URL.

Delivery-payload

Meshy stuurt een delivery terwijl een taak IN_PROGRESS is, en nog een wanneer de taak een definitieve status bereikt. Een taak kan zijn definitieve status bereiken zonder een IN_PROGRESS-delivery.

Elke delivery is een POST naar je payload-URL met deze headers:

Header	Waarde
`X-MESHY-API-WEBHOOK-SECRET-KEY`	Het secret van de webhook
`X-MESHY-API-WEBHOOK-USER-ID`	De ID van de Meshy-gebruiker die eigenaar is van de webhook
`Meshy-Webhook-Version`	`v1`, het formaat van de body
`Content-Type`	`application/json`
`User-Agent`	`MeshyAPIWebhook/1.0.0`

De JSON-body is het taakobject. Het is hetzelfde object dat het GET-endpoint van de taak retourneert, behalve progress. Een delivery verstuurt progress als een van deze waarden:

50 terwijl de taak IN_PROGRESS is
100 wanneer de taak slaagt
0 wanneer de taak mislukt of wordt geannuleerd

Zie de volgende secties voor de velden van elk taakobject, met een voorbeeld: