Webhooks

Webhooks memungkinkan Anda menerima pembaruan real-time dari Meshy ketika tugas API Anda selesai atau statusnya berubah. Setelah dikonfigurasi, Meshy akan mengirimkan payload event dalam format json ke URL yang Anda tentukan.

Mengapa Membuat Webhooks

Menggunakan webhooks memiliki beberapa keuntungan, terutama dalam hal memeriksa status tugas API secara otomatis. Webhooks memerlukan lebih sedikit usaha dan biaya dibandingkan dengan terus-menerus memeriksa API untuk mendapatkan pembaruan status tugas. Webhooks juga memungkinkan pembaruan hampir real-time dan pada akhirnya lebih baik dalam skala dibandingkan dengan polling API. Ini juga memungkinkan Anda untuk mengelola batasan tingkat Anda dengan lebih baik, terutama jika Anda terus-menerus melakukan polling.

Pengaturan & Konfigurasi

Untuk mengaktifkan webhooks, navigasikan ke halaman pengaturan API saat masuk ke aplikasi web Meshy. Temukan bagian "Webhooks" di bawah API Keys Anda dan klik tombol "Create Webhook". Berikan URL https yang Anda inginkan untuk menerima webhooks dan aktifkan webhook untuk secara otomatis menerima pembaruan tugas dari Meshy. Anda dapat memiliki maksimal 5 webhooks aktif per akun Meshy. Ketika sebuah webhook diaktifkan, semua pembaruan status tugas API akan secara otomatis dikirim ke URL payload. Untuk tujuan keamanan, kami hanya mengizinkan pengiriman webhooks ke URL https saat ini. Jika Anda ingin mengkonfigurasi pengujian lokal, lihat bagian berikut.

Persyaratan Pengiriman Webhook

Agar webhook Anda berfungsi normal dan terus menerima event:

  • Server Anda harus merespons dengan kode status HTTP di bawah 400 (misalnya, 200 OK, 202 Accepted).
  • Setiap respons dengan kode status >= 400 akan dianggap sebagai pengiriman gagal.
  • Kegagalan berturut-turut dapat:
    • Menyebabkan pembaruan progress tertunda atau tiba tidak sesuai urutan
    • Secara otomatis menonaktifkan webhook Anda setelah beberapa kali percobaan (lihat Kebijakan Auto-Disable)

Tip: Selalu kembalikan respons sukses setelah Anda memvalidasi dan menyimpan payload webhook, bahkan jika pemrosesan lebih lanjut terjadi secara asinkron.

Penerusan Webhooks untuk Pengujian Lokal

Jika Anda ingin menguji kode webhook Anda secara lokal, yang biasanya berada di alamat http, Anda dapat menggunakan URL proxy webhook untuk meneruskan webhooks ke komputer atau ruang kode Anda. Berikut adalah langkah-langkah yang direkomendasikan menggunakan smee.io, tetapi Anda dapat menggunakan layanan apa pun yang Anda inginkan untuk menghasilkan URL proxy webhook.

Dapatkan URL proxy webhook:

  1. Di browser Anda, navigasikan ke https://smee.io/
  2. Klik "Start a new channel"
  3. Salin URL lengkap di bawah "Webhook Proxy URL". Anda akan menggunakan URL ini dalam langkah-langkah pengaturan berikut.

Teruskan webhooks:

  1. Jika Anda belum menginstal smee-client, jalankan perintah berikut di terminal Anda.
npm install --global smee-client
  1. Untuk menerima webhooks yang diteruskan dari smee.io, jalankan perintah berikut di terminal Anda. Ganti WEBHOOK_PROXY_URL dengan URL proxy webhook Anda dari sebelumnya.
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

Anda akan melihat output yang terlihat seperti ini, 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
  1. Biarkan ini berjalan saat Anda menguji webhook Anda. Ketika Anda ingin menghentikan penerusan webhooks, masukkan Ctrl+C.
    Perhatikan bahwa path adalah /webhook dan port adalah 3000. Nilai-nilai ini mungkin berguna ketika Anda ingin mengatur kode Anda sendiri untuk menerima pengiriman webhook di kemudian hari.

Buat webhook:

Anda sekarang dapat menggunakan URL proxy webhook untuk membuat webhook baru di halaman pengaturan Meshy API.

Contoh Respons

Ketika status tugas berubah, Meshy akan mengirimkan payload webhook ke URL yang Anda konfigurasikan. Payload berisi objek tugas dalam format JSON. Untuk deskripsi lengkap dari semua properti objek tugas dan contoh payload, lihat: