Webhooks

Minta Meshy mengirim permintaan POST ke server Anda saat sebuah tugas API membuat progress atau selesai, sehingga Anda tidak perlu melakukan polling.

Mengapa menggunakan webhook

Webhook membutuhkan lebih sedikit kerja dan biaya dibandingkan melakukan polling status API untuk setiap tugas. Meshy mengirim setiap pembaruan saat terjadi, sehingga Anda mendapatkannya lebih cepat, dan webhook lebih mudah diskalakan dibandingkan polling. Anda juga mengirim lebih sedikit permintaan, sehingga menjaga Anda lebih jauh dari batas kecepatan (rate limits) Anda.

Menyiapkan webhook

Untuk menambahkan webhook, ikuti langkah-langkah berikut:

Buka halaman Webhooks di Developer Platform, lalu klik Create Webhook.
Pada Payload URL, masukkan URL yang menerima pengiriman. Meshy hanya mengirim melalui https://.
Simpan salinan Webhook Secret yang diisi otomatis oleh dialog tersebut. Setiap pengiriman membawanya, sehingga server Anda dapat memeriksa bahwa permintaan tersebut benar-benar berasal dari Meshy. Untuk webhook yang sudah Anda miliki, klik ikon mata pada kolom Secret-nya untuk melihatnya.
Pilih Active, lalu klik Confirm.

Setiap akun dapat memiliki 5 webhook aktif, dan 10 secara total. Setiap webhook aktif menerima pembaruan status dari semua tugas API Anda.

Untuk menguji webhook dengan server di komputer Anda, lihat Menguji di komputer Anda.

Menangani pengiriman

Untuk menerima sebuah pengiriman, tanggapi dengan status di bawah 400, seperti 200 atau 202. Meshy menunggu sekitar 25 detik untuk respons, jadi simpan pengiriman tersebut dan beri respons terlebih dahulu. Lakukan pekerjaan yang lebih lambat setelah itu, seperti mengunduh model.

Status 400 ke atas, atau tidak ada respons sama sekali, dianggap sebagai pengiriman yang gagal. Meshy akan mencobanya kembali dengan jeda yang semakin lama di antara setiap percobaan, hingga 4 kali untuk pembaruan IN_PROGRESS dan hingga 9 kali untuk status akhir. Jika 20 pembaruan berturut-turut gagal di setiap percobaan, Meshy dapat menonaktifkan webhook tersebut. Untuk mengaktifkannya kembali, edit webhook tersebut di halaman Webhooks dan pilih Active.

Tulis kode Anda untuk kasus-kasus berikut:

Pengiriman dapat tiba dalam urutan yang tidak berurutan. Pengiriman IN_PROGRESS dapat tiba setelah pengiriman final, jadi jangan biarkan itu menggantikan status final.
Pembaruan yang sama dapat tiba lebih dari sekali. Tangani setiap pasangan id dan status hanya satu kali.
Siapa pun yang mengetahui URL Anda dapat mengirimkan permintaan ke sana. Bandingkan X-MESHY-API-WEBHOOK-SECRET-KEY dengan salinan secret Anda, dan tolak permintaan yang tidak cocok.

Jika pengiriman final suatu tugas belum tiba setelah sekitar dua kali waktu normal tugas tersebut, ambil tugas tersebut dari endpoint GET-nya. Untuk waktu normal dan berapa lama harus menunggu, lihat Siklus hidup tugas.

Menguji di komputer Anda

Meshy hanya mengirim ke URL publik https://, sehingga tidak dapat langsung menjangkau server di komputer Anda. Untuk menguji kode di komputer Anda, teruskan (forward) URL publik ke komputer tersebut menggunakan proxy webhook. Langkah-langkah berikut menggunakan smee.io, dan layanan proxy webhook apa pun bekerja dengan cara yang sama.

Buka smee.io dan klik Start a new channel. Salin URL di bawah Webhook Proxy URL.
Jika Anda belum memiliki klien smee, instal terlebih dahulu:
```
npm install --global smee-client
```
Teruskan channel tersebut ke server Anda. Ganti WEBHOOK_PROXY_URL dengan URL proxy webhook Anda:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
Outputnya akan terlihat seperti berikut, di mana WEBHOOK_PROXY_URL adalah URL proxy webhook Anda:
```
Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
```
Biarkan ini terus berjalan selama Anda menguji. Untuk menghentikan penerusan, tekan Ctrl+C. Server Anda menerima pengiriman pada port 3000 di path /webhook, jadi siapkan kode Anda untuk mendengarkan di sana.
Di halaman Webhooks, buat sebuah webhook dengan URL proxy webhook tersebut sebagai Payload URL-nya.

Payload pengiriman

Meshy mengirim sebuah pengiriman saat tugas berstatus IN_PROGRESS, dan satu lagi saat tugas mencapai status final. Sebuah tugas dapat mencapai status final tanpa pengiriman IN_PROGRESS.

Setiap pengiriman adalah permintaan POST ke URL payload Anda dengan header-header berikut:

Header	Nilai
`X-MESHY-API-WEBHOOK-SECRET-KEY`	Secret milik webhook tersebut
`X-MESHY-API-WEBHOOK-USER-ID`	ID pengguna Meshy yang memiliki webhook tersebut
`Meshy-Webhook-Version`	`v1`, format dari body
`Content-Type`	`application/json`
`User-Agent`	`MeshyAPIWebhook/1.0.0`

Body JSON-nya adalah objek tugas. Objek ini sama dengan objek yang dikembalikan oleh endpoint GET dari tugas tersebut, kecuali progress. Sebuah pengiriman mengirim progress sebagai salah satu dari nilai-nilai berikut:

50 saat tugas berstatus IN_PROGRESS
100 saat tugas berhasil
0 saat tugas gagal atau dibatalkan

Untuk field-field dari setiap objek tugas, beserta contohnya, lihat bagian-bagian berikut: