Webhooks

Webhooks membolehkan anda menerima kemas kini masa nyata daripada Meshy apabila tugas API anda selesai atau menukar status. Setelah dikonfigurasikan, Meshy akan menghantar (POST) payload acara dalam format json ke URL yang anda tentukan.

Mengapa Mencipta Webhooks

Menggunakan webhooks mempunyai beberapa kelebihan, terutamanya berkaitan dengan menyemak status tugas API secara automatik. Webhooks memerlukan lebih sedikit usaha dan kos berbanding meninjau (polling) API secara berterusan untuk mendapatkan kemas kini status tugas. Webhooks juga membolehkan kemas kini hampir masa nyata dan pada akhirnya berskala lebih baik berbanding polling API. Ini juga membolehkan anda menguruskan had kadar (rate limit) anda dengan lebih baik, terutamanya jika anda melakukan polling secara berterusan.

Persediaan & Konfigurasi

Untuk mendayakan webhooks, buka halaman Webhooks di Platform Pembangun dan klik butang "Create Webhook". Berikan URL https yang anda mahu untuk menerima webhooks dan dayakan webhook tersebut untuk menerima kemas kini tugas secara automatik daripada Meshy. Anda boleh mempunyai maksimum 5 webhook aktif bagi setiap akaun Meshy. Apabila sesuatu webhook didayakan, semua kemas kini status tugas API akan dihantar secara automatik ke URL payload. Bagi tujuan keselamatan, kami hanya membenarkan penghantaran webhooks ke URL https pada masa ini. Jika anda ingin mengkonfigurasi ujian tempatan, sila rujuk bahagian berikut.

Keperluan Penghantaran Webhook

Untuk webhook anda berfungsi dengan normal dan terus menerima acara:

  • Pelayan anda mesti membalas dengan kod status HTTP di bawah 400 (contohnya, 200 OK, 202 Accepted).
  • Sebarang respons dengan kod status >= 400 akan dianggap sebagai penghantaran yang gagal.
  • Beberapa kegagalan berturutan mungkin:
    • Menyebabkan kemas kini progress lambat atau tiba tidak mengikut urutan
    • Melumpuhkan webhook anda secara automatik selepas beberapa percubaan berulang (lihat Dasar Auto-Disable)

Tip: Sentiasa kembalikan respons berjaya selepas anda mengesahkan dan menyimpan payload webhook, walaupun pemprosesan selanjutnya berlaku secara tak segerak (asynchronous).

Memajukan Webhooks untuk Ujian Tempatan

Jika anda ingin menguji kod webhook anda secara tempatan, yang biasanya berada di alamat http, anda boleh menggunakan URL proksi webhook untuk memajukan webhooks ke komputer atau codespace anda. Berikut adalah langkah-langkah yang disyorkan menggunakan smee.io, tetapi anda boleh menggunakan mana-mana perkhidmatan yang anda mahu untuk menjana URL proksi webhook.

Dapatkan URL proksi webhook:

  1. Dalam pelayar anda, navigasi ke https://smee.io/
  2. Klik "Start a new channel"
  3. Salin URL penuh di bawah "Webhook Proxy URL". Anda akan menggunakan URL ini dalam langkah-langkah persediaan berikutnya.

Majukan webhooks:

  1. Jika anda belum memasang smee-client, jalankan arahan berikut dalam terminal anda.
npm install --global smee-client
  1. Untuk menerima webhooks yang dimajukan daripada smee.io, jalankan arahan berikut dalam terminal anda. Gantikan WEBHOOK_PROXY_URL dengan URL proksi webhook anda dari sebelumnya.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Anda sepatutnya melihat output yang kelihatan seperti ini, di mana WEBHOOK_PROXY_URL adalah URL proksi webhook anda:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
  1. Kekalkan ini berjalan semasa anda menguji webhook anda. Apabila anda ingin berhenti memajukan webhooks, tekan Ctrl+C.
    Perhatikan bahawa path adalah /webhook dan port adalah 3000. Nilai-nilai ini mungkin berguna apabila anda ingin menyediakan kod anda sendiri untuk menerima penghantaran webhook kemudian.

Cipta webhook:

Anda kini boleh menggunakan URL proksi webhook untuk mencipta webhook baharu di halaman Webhooks.

Contoh Respons

Apabila status tugas berubah, Meshy akan menghantar (POST) payload webhook ke URL yang anda konfigurasikan. Payload tersebut mengandungi objek tugas dalam format JSON. Untuk penerangan lengkap mengenai semua sifat objek tugas dan contoh payload, sila rujuk: