Webhooks

Webhooks membolehkan anda menerima kemas kini masa nyata daripada Meshy apabila tugas API anda selesai atau statusnya berubah. Setelah dikonfigurasi, Meshy akan menghantar payload acara dalam format json ke URL yang anda tentukan.

Mengapa Mencipta Webhooks

Menggunakan webhooks mempunyai beberapa kelebihan, terutamanya berkaitan dengan memeriksa status tugas API secara automatik. Webhooks memerlukan usaha dan kos yang lebih rendah berbanding dengan sentiasa memanggil API untuk mendapatkan kemas kini status tugas. Webhooks juga membolehkan kemas kini hampir masa nyata dan akhirnya lebih baik daripada pemanggilan API. Ini juga membolehkan anda menguruskan had kadar anda dengan lebih baik, terutamanya jika anda sentiasa memanggil.

Persediaan & Konfigurasi

Untuk mengaktifkan webhooks, navigasi ke halaman tetapan API apabila log masuk ke aplikasi web Meshy. Cari bahagian "Webhooks" di bawah API Keys anda dan klik butang "Create Webhook". Berikan URL https yang anda inginkan untuk menerima webhooks dan aktifkan webhook untuk menerima kemas kini tugas secara automatik daripada Meshy. Anda boleh mempunyai maksimum 5 webhooks aktif bagi setiap akaun Meshy. Apabila webhook diaktifkan, semua kemas kini status tugas API akan dihantar secara automatik ke URL payload. Untuk tujuan keselamatan, kami hanya membenarkan penghantaran webhooks ke URL https pada masa ini. Jika anda ingin mengkonfigurasi ujian tempatan, lihat bahagian berikut.

Keperluan Penghantaran Webhook

Untuk webhook anda berfungsi dengan normal dan terus menerima acara:

  • Pelayan anda mesti bertindak balas dengan kod status HTTP di bawah 400 (contohnya, 200 OK, 202 Accepted).
  • Sebarang respons dengan kod status >= 400 akan dianggap sebagai penghantaran gagal.
  • Kegagalan berturut-turut yang banyak boleh:
    • Menyebabkan kemas kini progress ditangguhkan atau tiba tidak mengikut urutan
    • Menyahaktifkan webhook anda secara automatik selepas percubaan berulang kali (lihat Polisi Auto-Disable)

Petua: Sentiasa kembalikan respons kejayaan selepas anda mengesahkan dan menyimpan payload webhook, walaupun pemprosesan lanjut berlaku secara asinkron.

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 ruang kod anda. Berikut adalah langkah-langkah yang disyorkan menggunakan smee.io, tetapi anda boleh menggunakan mana-mana perkhidmatan yang anda suka 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 berikut.

Majukan webhooks:

  1. Jika anda belum memasang smee-client, jalankan perintah berikut dalam terminal anda.
npm install --global smee-client
  1. Untuk menerima webhooks yang dimajukan dari smee.io, jalankan perintah 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. Biarkan ini berjalan semasa anda menguji webhook anda. Apabila anda ingin berhenti memajukan webhooks, masukkan Ctrl+C.
    Perhatikan bahawa laluan 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 baru di halaman tetapan Meshy API.

Contoh Respons

Apabila status tugas berubah, Meshy akan menghantar payload webhook ke URL yang anda konfigurasikan. Payload mengandungi objek tugas dalam format JSON. Untuk penerangan lengkap tentang semua sifat objek tugas dan contoh payload, lihat: