Webhooks

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

Mengapa Membuat Webhooks

Menggunakan webhooks memiliki beberapa keuntungan, terutama terkait pemeriksaan status tugas API secara otomatis. Webhooks memerlukan lebih sedikit upaya dan biaya dibandingkan terus-menerus melakukan polling API untuk mendapatkan pembaruan status tugas. Webhooks juga memungkinkan pembaruan hampir real-time dan pada akhirnya berskala lebih baik daripada polling API. Ini juga memungkinkan Anda mengelola batas laju dengan lebih baik, terutama jika Anda melakukan polling secara terus-menerus.

Penyiapan & Konfigurasi

Untuk mengaktifkan webhooks, buka halaman pengaturan API saat masuk ke aplikasi web Meshy. Temukan bagian "Webhooks" di bawah API key Anda dan klik tombol "Create Webhook". Berikan URL https yang Anda inginkan untuk menerima webhooks dan aktifkan webhook agar secara otomatis menerima pembaruan tugas dari Meshy. Anda dapat memiliki maksimal 5 webhooks aktif per akun Meshy. Saat 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 peristiwa:

  • Server Anda harus merespons dengan kode status HTTP di bawah 400 (misalnya, 200 OK, 202 Accepted).
  • Respons apa pun dengan kode status >= 400 akan diperlakukan sebagai pengiriman yang gagal.
  • Beberapa kegagalan berturut-turut dapat:
    • Menyebabkan pembaruan progress tertunda atau tiba tidak berurutan
    • Menonaktifkan webhook Anda secara otomatis setelah percobaan berulang (lihat Kebijakan Penonaktifan 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 dalam langkah-langkah penyiapan 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 tetap berjalan saat Anda menguji webhook Anda. Saat Anda ingin berhenti meneruskan webhooks, masukkan Ctrl+C.
    Perhatikan bahwa path adalah /webhook dan port adalah 3000. Nilai-nilai ini mungkin berguna saat Anda ingin menyiapkan kode Anda sendiri untuk menerima pengiriman webhook nanti.

Buat webhook:

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

Contoh Respons

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