Webhooks

Jadikan Meshy menghantar permintaan POST ke pelayan anda apabila tugas API membuat progress atau selesai, supaya anda tidak perlu melakukan polling.

Sebab menggunakan webhook

Webhooks memerlukan kerja yang lebih sedikit dan kos yang lebih rendah berbanding melakukan polling API untuk status setiap tugas. Meshy menghantar setiap kemas kini sebaik sahaja ia berlaku, jadi anda menerimanya lebih awal, dan webhook berskala lebih baik berbanding polling. Anda juga menghantar permintaan yang lebih sedikit, yang mengekalkan jarak anda daripada had kadar anda.

Sediakan webhook

Untuk menambah webhook, ikuti langkah-langkah berikut:

Buka laman Webhooks dalam Developer Platform, dan klik Create Webhook.
Dalam Payload URL, masukkan URL yang menerima penghantaran. Meshy hanya menghantar melalui https://.
Simpan salinan Webhook Secret yang diisi secara automatik oleh dialog tersebut. Setiap penghantaran membawanya, supaya pelayan anda boleh menyemak bahawa permintaan itu datang daripada Meshy. Untuk webhook yang anda sudah ada, klik ikon mata dalam lajur Secret-nya untuk melihatnya.
Pilih Active, dan klik Confirm.

Setiap akaun boleh mempunyai 5 webhook aktif, dan 10 secara keseluruhan. Setiap webhook aktif menerima kemas kini status bagi semua tugas API anda.

Untuk menguji webhook dengan pelayan pada komputer anda, lihat Uji pada komputer anda.

Kendalikan penghantaran

Untuk menerima penghantaran, berikan respons dengan status di bawah 400, seperti 200 atau 202. Meshy menunggu kira-kira 25 saat untuk respons, jadi simpan penghantaran dan berikan respons dahulu. Lakukan kerja yang lambat selepas itu, seperti memuat turun model.

Status 400 atau ke atas, atau tiada respons, dikira sebagai penghantaran yang gagal. Meshy akan mencuba semula dengan jeda yang lebih panjang antara setiap percubaan, sehingga 4 kali untuk kemas kini IN_PROGRESS dan sehingga 9 kali untuk status akhir. Jika 20 kemas kini berturut-turut gagal pada setiap percubaan, Meshy boleh menyahaktifkan webhook tersebut. Untuk mengaktifkannya semula, edit webhook tersebut pada laman Webhooks dan pilih Active.

Tulis kod anda untuk kes-kes berikut:

Penghantaran boleh tiba tidak mengikut susunan. Penghantaran IN_PROGRESS boleh tiba selepas penghantaran akhir, jadi jangan biarkan ia menggantikan status akhir.
Kemas kini yang sama boleh tiba lebih daripada sekali. Kendalikan setiap pasangan id dan status sekali sahaja.
Sesiapa yang mengetahui URL anda boleh menghantar permintaan kepadanya. Bandingkan X-MESHY-API-WEBHOOK-SECRET-KEY dengan salinan rahsia anda, dan tolak permintaan yang tidak sepadan.

Jika penghantaran akhir sesuatu tugas belum tiba selepas lebih kurang dua kali ganda masa biasa tugas tersebut, dapatkan tugas itu daripada endpoint GET-nya. Untuk masa biasa dan berapa lama perlu menunggu, lihat Kitaran hayat tugas.

Uji pada komputer anda

Meshy hanya menghantar ke URL https:// yang awam, jadi ia tidak dapat mencapai pelayan pada komputer anda secara langsung. Untuk menguji kod pada komputer anda, teruskan URL awam kepadanya dengan proksi webhook. Langkah-langkah ini menggunakan smee.io, dan mana-mana perkhidmatan proksi webhook berfungsi dengan cara yang sama.

Buka smee.io dan klik Start a new channel. Salin URL di bawah Webhook Proxy URL.
Jika anda belum mempunyai klien smee, pasangnya:
```
npm install --global smee-client
```
Teruskan saluran tersebut ke pelayan anda. Gantikan WEBHOOK_PROXY_URL dengan URL proksi webhook anda:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
Outputnya kelihatan seperti ini, dengan WEBHOOK_PROXY_URL ialah URL proksi webhook anda:
```
Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
```
Biarkan ia berjalan semasa anda menguji. Untuk menghentikan penerusan, tekan Ctrl+C. Pelayan anda menerima penghantaran pada port 3000 di laluan /webhook, jadi sediakan kod anda untuk mendengar di sana.
Pada laman Webhooks, cipta webhook dengan URL proksi webhook sebagai Payload URL-nya.

Payload penghantaran

Meshy menghantar penghantaran semasa tugas berada dalam status IN_PROGRESS, dan satu lagi apabila tugas mencapai status akhir. Sesuatu tugas boleh mencapai status akhirnya tanpa penghantaran IN_PROGRESS.

Setiap penghantaran ialah POST ke URL payload anda dengan header-header berikut:

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

Badan JSON tersebut ialah objek tugas. Ia adalah objek yang sama yang dikembalikan oleh endpoint GET tugas tersebut, kecuali progress. Satu penghantaran menghantar progress sebagai salah satu daripada nilai berikut:

50 semasa tugas berada dalam status IN_PROGRESS
100 apabila tugas berjaya
0 apabila tugas gagal atau dibatalkan

Untuk medan-medan bagi setiap objek tugas, berserta contoh, lihat bahagian-bahagian berikut: