Webhooks

Webhooks memungkinkan Anda menerima pembaruan secara real-time dari Meshy saat tugas API Anda selesai atau berubah status. Setelah dikonfigurasi, Meshy akan mengirimkan (POST) payload event dalam format json ke URL yang Anda tentukan.

Alasan 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 melakukan polling ke API untuk mendapatkan pembaruan status tugas. Webhooks juga memungkinkan pembaruan yang hampir real-time dan pada akhirnya lebih skalabel dibandingkan polling API. Hal ini juga memungkinkan Anda mengelola rate limit dengan lebih baik, terutama jika Anda melakukan polling secara terus-menerus.

Pengaturan & Konfigurasi

Untuk mengaktifkan webhooks, buka halaman Webhooks di Developer Platform 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, saat ini kami hanya mengizinkan pengiriman webhooks ke URL https. Jika Anda ingin mengonfigurasi 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).
  • Respons apa pun dengan kode status >= 400 akan dianggap sebagai pengiriman yang gagal.
  • Beberapa kegagalan berturut-turut dapat:
    • Menyebabkan pembaruan progress tertunda atau tiba tidak berurutan
    • Menonaktifkan webhook Anda secara otomatis setelah beberapa kali percobaan yang berulang (lihat Kebijakan Nonaktif Otomatis)

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

Meneruskan 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 codespace 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, buka https://smee.io/
  2. Klik "Start a new channel"
  3. Salin URL lengkap di bawah "Webhook Proxy URL". Anda akan menggunakan URL ini pada langkah-langkah pengaturan berikutnya.

Teruskan webhooks:

  1. Jika Anda belum memiliki smee-client terinstal, 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 tetap berjalan selama Anda menguji webhook Anda. Ketika Anda ingin menghentikan penerusan webhooks, tekan Ctrl+C.
    Perhatikan bahwa path-nya adalah /webhook dan port-nya adalah 3000. Nilai-nilai ini mungkin berguna ketika Anda ingin menyiapkan 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 Webhooks.

Contoh Respons

Ketika status tugas berubah, Meshy akan mengirimkan (POST) payload webhook ke URL yang telah Anda konfigurasi. Payload tersebut berisi objek tugas dalam format JSON. Untuk deskripsi lengkap mengenai semua properti objek tugas dan contoh payload, lihat: