Webhooks

Have Meshy send a POST request to your server when an API task makes progress or finishes, so you don't need to poll.

Why use webhooks

Webhooks take less work and cost less than polling the API for each task's status. Meshy sends each update as it happens, so you get it sooner, and webhooks scale better than polling. You also send fewer requests, which keeps you further from your rate limits.

Set up a webhook

To add a webhook, follow these steps:

Open the Webhooks page in the Developer Platform, and click Create Webhook.
In Payload URL, enter the URL that receives the deliveries. Meshy delivers only over https://.
Select Active, and click Confirm.

Each account can have 5 active webhooks, and 10 in total. Every active webhook receives the status updates of all your API tasks.

To test a webhook with a server on your computer, see Test on your computer.

Handle a delivery

To accept a delivery, respond with a status below 400, such as 200 or 202. Meshy waits about 25 seconds for the response, so store the delivery and respond first. Do the slow work after that, such as downloading the model.

A status of 400 or above, or no response, counts as a failed delivery. Meshy retries it with longer waits between attempts, up to 4 times for an IN_PROGRESS update and up to 9 times for a final status. If 20 updates in a row fail every attempt, Meshy can deactivate the webhook. To turn it back on, edit it on the Webhooks page and select Active.

Write your code for these cases:

Deliveries can arrive out of order. An IN_PROGRESS delivery can arrive after the final one, so don't let it replace a final status.
The same update can arrive more than once. Handle each pair of id and status once.

If a task's final delivery hasn't arrived after about twice the task's typical time, get the task from its GET endpoint. For typical times and how long to wait, see Task lifecycle.

Test on your computer

Meshy delivers only to a public https:// URL, so it can't reach a server on your computer directly. To test code on your computer, forward a public URL to it with a webhook proxy. These steps use smee.io, and any webhook proxy service works the same way.

Open smee.io and click Start a new channel. Copy the URL under Webhook Proxy URL.
If you don't have the smee client yet, install it:
```
npm install --global smee-client
```
Forward the channel to your server. Replace WEBHOOK_PROXY_URL with your Webhook Proxy URL:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
The output looks like this, where WEBHOOK_PROXY_URL is your Webhook Proxy URL:
```
Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
```
Keep it running while you test. To stop forwarding, press Ctrl+C. Your server receives the deliveries on port 3000 at the path /webhook, so set up your code to listen there.
On the Webhooks page, create a webhook with the Webhook Proxy URL as its Payload URL.

Delivery payload

Meshy sends a delivery while a task is IN_PROGRESS, and another when the task reaches a final status. A task can reach its final status without an IN_PROGRESS delivery.

Each delivery is a POST to your Payload URL with the task object as its JSON body. It's the same object that the task's GET endpoint returns, except progress. A delivery sends progress as one of these values:

50 while the task is IN_PROGRESS
100 when the task succeeds
0 when the task fails or is canceled

For the fields of each task object, with an example, see the following sections: