Webhook

Kirim permintaan HTTP POST ke API eksternal saat IoT Logic menerima data perangkat. Buat payload JSON kustom dengan nilai statis dan atribut telemetri dinamis.

Ikhtisar teknis dan kemampuan

Webhook Simpul ini memungkinkan pemicu tindakan tertentu secara real-time di sistem eksternal. Simpul ini mengirim permintaan HTTP POST ke titik akhir yang ditentukan saat menerima data dari simpul yang terhubung. Kemudian, simpul ini menyusun payload JSON kustom dengan atribut statis dan dinamis, serta menjalankan panggilan API ke layanan pihak ketiga.

Simpul ini memperluas kemampuan IoT Logic melampaui pemrosesan dan transmisi data, memungkinkan integrasi langsung dengan platform perpesanan, sistem ERM dan CRM, serta aplikasi kustom untuk memulai tindakan otomatis berdasarkan konfigurasi aliran Anda.

Simpul Webhook dikonfigurasi secara terpisah untuk setiap aliran di UI platform Navixy. Simpul Webhook berfungsi sebagai titik terminasi dalam aliran dan memerlukan setidaknya satu koneksi masuk agar dapat berfungsi. Simpul ini tidak dapat meneruskan data ke simpul berikutnya.

Cara kerja simpul Webhook

Saat data mencapai simpul Webhook melalui koneksi masuk, simpul ini segera mengeksekusi permintaan HTTP POST ke titik akhir yang dikonfigurasi. Simpul ini:

1. Mengumpulkan nilai saat ini untuk semua atribut dari simpul hulu yang terhubung

2. Mengganti referensi atribut dinamis (mis., {{speed}}) dengan nilai aktual dari pesan masuk

3. Menyusun payload JSON lengkap dengan mempertahankan struktur yang Anda tentukan

4. Mengirim permintaan HTTP POST dengan header yang ditentukan ke titik akhir target

5. Melanjutkan tanpa menunggu respons, sehingga aliran dapat segera berlanjut

Simpul Webhook dipicu sekali untuk setiap pesan yang mencapainya. Jika beberapa cabang paralel mengirim data ke Webhook, simpul ini dipicu secara terpisah untuk setiap pesan masuk. Eksekusi ini terjadi secara independen tanpa memblokir simpul lain dalam aliran, memastikan pemrosesan data berkelanjutan tanpa memandang waktu respons sistem eksternal.

Setiap Webhook hasil pemicu node muncul di Penganalisis Data sebagai atribut yang dinamai sesuai dengan ID node (ditampilkan di dialog konfigurasi node, misalnya webhook_1a2b3c4d). Nilainya adalah 0 saat simpul belum dipicu dan 1 saat sudah, sehingga Anda dapat mengonfirmasi pengiriman dan membedakan beberapa simpul Webhook dalam aliran yang sama.

Integrasi arsitektur aliran

Simpul Webhook berfungsi sebagai titik terminasi yang mengubah data perangkat yang telah diproses menjadi panggilan API eksternal. Alih-alih mengalirkan semua data perangkat secara terus-menerus seperti simpul Titik Akhir Output, webhook menjalankan permintaan API yang terarah dengan payload yang dikonfigurasi secara presisi. Arsitektur ini memungkinkan:

• Automasi berbasis peristiwa: Memicu alur kerja eksternal berdasarkan kondisi perangkat, metrik yang dihitung, atau pola data tertentu yang diidentifikasi sebelumnya dalam aliran

• Pengiriman data selektif: Mengirim hanya atribut yang relevan ke sistem eksternal, sehingga mengurangi transfer data yang tidak perlu dan biaya API

• Eksekusi paralel: Beroperasi bersama simpul keluaran lainnya, memungkinkan pemicu Webhook simultan dan aliran data berkelanjutan ke tujuan yang berbeda

• Integrasi multisumber: Menerima koneksi masuk dari beberapa cabang paralel dan mengakses atribut dari semua simpul yang terhubung

Kemampuan node

Blok Simpul Webhook menawarkan:

• Eksekusi HTTP POST: Mengirim permintaan HTTP POST yang disesuaikan ke titik akhir yang dapat diakses menggunakan protokol HTTP atau HTTPS (HTTPS sangat disarankan)

• Penyusunan payload dinamis: Membangun isi permintaan JSON dengan menggabungkan nilai statis dengan atribut dinamis dari mana saja di aliran menggunakan {{attribute_name}} sintaks

• Konfigurasi header kustom: Mendukung hingga 10 header HTTP yang ditentukan pengguna untuk autentikasi dan kebutuhan khusus API

• Dukungan atribut bertingkat: Merujuk pada struktur atribut kompleks, termasuk objek bertingkat dan array dalam payload JSON

• Eksekusi independen: Dipicu tanpa menunggu respons atau memblokir aliran, sehingga memungkinkan operasi yang andal tanpa memandang ketersediaan sistem eksternal

Opsi konfigurasi

Simpul Webhook memungkinkan Anda menentukan bagaimana aliran Anda akan berkomunikasi dengan sistem eksternal melalui panggilan API HTTP.

Mari kita lihat elemen apa yang digunakan node ini dan apa yang dapat Anda konfigurasi saat menggunakannya.

Langkah konfigurasi

1

Tentukan nama node

Masukkan nama deskriptif yang mengidentifikasi tujuan Webhook.

• Gunakan nama yang menunjukkan layanan atau tindakan target (mis., "Aturan peringatan kecepatan Slack" atau "Pembuatan tiket CRM")

• Nama ini muncul di diagram aliran agar mudah dikenali

2

ID node (dihasilkan secara otomatis)

Di bawah kolom Nama, dialog menampilkan sebuah ID node (misalnya, webhook_1a2b3c4d). Kolom ini hanya baca — Anda tidak dapat mengedit atau menetapkan nilainya.

• ID dihasilkan otomatis saat node dibuat dan tetap sama selama masa pakai node

• Gunakan ini untuk membedakan hasil simpul ini dari simpul Webhook lainnya di Penganalisis Data, di mana atribut tersebut muncul sebagai atribut yang menampilkan 0 (belum dipicu) atau 1 (dipicu)

3

Konfigurasikan URL titik akhir

Masukkan URL lengkap tempat permintaan POST dikirim.

• Sertakan protokol: http:// atau https:// (HTTPS sangat disarankan)

• Pastikan URL mengarah ke titik akhir API yang valid yang menerima permintaan POST

• Contoh: https://api.example.com/v1/webhooks/device-aturan-peringatan

4

Tentukan header HTTP

Tambahkan header apa pun yang diperlukan oleh API target Anda.

1. Klik Tambahkan header untuk membuat pasangan kunci-nilai header Semua header dikonfigurasi oleh pengguna, termasuk Content-Type. Header yang umum meliputi:

   • Content-Type: application/json (diperlukan untuk payload JSON)

   • Authorization: Bearer <token> (untuk autentikasi API)

   • Kunci API khusus atau header autentikasi sesuai persyaratan layanan

2. Klik ikon hapus untuk menghapus header satu per satu

Maksimum 10 header didukung

5

Buat body permintaan

Beralih ke Isi tab dan tentukan struktur JSON yang dikirim ke endpoint:

• Masukkan sintaks JSON yang valid di kolom Body

• Gunakan {{attribute_name}} untuk mereferensikan atribut apa pun dari node yang terhubung

• Mendukung struktur JSON bertingkat dan array

• Referensi atribut berfungsi dengan jalur bertingkat (mis., {{location.latitude}})

• Jika atribut yang direferensikan bernilai null atau tidak ada, nilai null dikirim dalam JSON

Contoh isi Webhook dengan atribut dinamis:

{
  "alert_type": "pelanggaran_kecepatan",
  "device_id": "{{device_id}}",
  "current_speed": "{{speed_mph}}",
  "threshold_exceeded": 80,
  "location": {
    "lat": "{{latitude}}",
    "lng": "{{longitude}}"
  },
  "timestamp": "{{message_time}}",}
  "supir": "{{hardware_key}}"
}

6

Simpan konfigurasi Anda

Klik Terapkan perubahan untuk menyimpan pengaturan node Webhook.

Perilaku eksekusi Webhook

Webhook dieksekusi tanpa menunggu respons dari endpoint eksternal. Keberhasilan atau kegagalan permintaan Webhook tidak memengaruhi kelangsungan operasi aliran atau mencegah node lain memproses data.

Saat ini, eksekusi Webhook tidak mencakup percobaan ulang otomatis, pencatatan percobaan yang gagal, atau penanganan respons. Jika sebuah endpoint mengembalikan kesalahan atau mengalami time-out, Webhook akan dipicu lagi pada pesan masuk berikutnya. Pembaruan mendatang dapat mencakup pembatasan laju yang ditentukan oleh tujuan dan antrean permintaan.

Webhook vs streaming data berkelanjutan

Simpul Webhook secara mendasar berbeda dari simpul Titik Akhir Output dalam tujuan dan pola pelaksanaan:

Simpul Webhook	simpul Titik Akhir Output
Menjalankan panggilan API terpisah pada setiap pesan, mengirimkan payload khusus yang Anda tentukan. Ideal untuk memicu tindakan eksternal, mengirim notifikasi, atau mentransmisikan data selektif ke API REST.	Mempertahankan aliran data berkelanjutan melalui MQTT, mentransmisikan data perangkat lengkap dalam format Navixy Generic Protocol. Dirancang untuk pengumpulan telemetri berkelanjutan dan pemantauan waktu nyata.

Pilih webhook saat Anda perlu memicu otomatisasi eksternal atau mengirim hanya atribut tertentu ke endpoint API. Gunakan endpoint keluaran untuk umpan data berkelanjutan ke platform analitik atau sistem pemantauan. Keduanya dapat digunakan bersama dalam aliran yang sama.

Integrasi dengan sistem eksternal

Node Webhook unggul dalam memicu tindakan berbasis peristiwa pada sistem yang menyediakan API REST. Pola integrasi umum meliputi:

• Platform pesan: Kirim notifikasi ke Slack, Microsoft Teams, WhatsApp, atau Telegram saat kondisi perangkat memenuhi kriteria tertentu

• Sistem ERP: Sinkronkan data perangkat dengan platform perencanaan sumber daya perusahaan untuk memperbarui tingkat inventaris, memicu alur kerja pengadaan, atau mencatat penggunaan peralatan untuk penjadwalan pemeliharaan

• Sistem tiket: Secara otomatis membuat tiket dukungan atau permintaan layanan di platform CRM saat masalah perangkat terdeteksi

• Layanan peringatan: Memicu notifikasi SMS, email, atau push melalui layanan seperti Twilio, SendGrid, atau Firebase saat ambang batas terlampaui

• Otomasi bisnis: Memulai alur kerja di alat seperti Zapier, Make (Integromat), atau n8n berdasarkan telemetri perangkat

• Sistem telematika: Memicu tindakan atau otomasi tertentu dalam solusi telematika pihak ketiga berdasarkan data yang telah diproses, sehingga memungkinkan alur kerja berbasis peristiwa seperti perhitungan ulang rute, notifikasi supir, atau pembaruan status di sistem armada eksternal

• Aplikasi kustom: Mengaktifkan logika bisnis milik sendiri dengan mengirimkan peristiwa perangkat ke API internal

Pertanyaan yang sering diajukan

Bagaimana cara memicu Webhook hanya dalam kondisi tertentu?

Gunakan Logika node untuk menerapkan logika kondisional sebelum Webhook. Logika node dapat mengevaluasi atribut perangkat dan meneruskan data ke Webhook hanya saat kondisi terpenuhi. Untuk detail, lihat Logika.

Bisakah saya menggunakan beberapa node Webhook dalam aliran yang sama?

Ya. Sertakan beberapa node Webhook dengan konfigurasi berbeda untuk memicu berbagai sistem eksternal berdasarkan data perangkat yang sama. Setiap Webhook dipicu secara independen saat menerima data.

Apa yang terjadi jika permintaan Webhook gagal?

Webhook dipicu tanpa menunggu respons dan tidak mencoba ulang secara otomatis. Jika endpoint eksternal tidak tersedia atau mengembalikan galat, aliran tetap memproses secara normal. Webhook akan mencoba dipicu lagi saat pesan berikutnya tiba. Saat ini, belum ada pencatatan untuk percobaan Webhook yang gagal.

Bagaimana cara mengautentikasi dengan API eksternal?

Konfigurasikan autentikasi sepenuhnya melalui header kustom. Pendekatan umum:

• Token Bearer: Tambahkan header Authorization dengan nilai Bearer your_token_here

• Kunci API: Tambahkan header kustom sesuai yang ditentukan penyedia API Anda

• Autentikasi dasar: Tambahkan header Authorization dengan nilai Basic base64_encoded_credentials

Selalu sertakan Content-Type: application/json sebagai header saat mengirim payload JSON.

Bisakah saya merujuk atribut dari beberapa node yang terhubung?

Ya. Node Webhook dapat mengakses atribut dari node mana pun yang terhubung kepadanya, termasuk cabang paralel. Jika beberapa node mengirim data ke Webhook, Webhook dipicu sekali untuk setiap pesan masuk dan dapat merujuk atribut dari jalur sumber pesan tersebut.

Data apa yang dapat saya sertakan dalam isi Webhook?

Anda dapat menyertakan kombinasi apa pun dari:

• Nilai statis yang ditentukan langsung dalam konfigurasi JSON Anda

• Atribut dinamis dari aliran menggunakan {{attribute_name}} sintaks

• Atribut bertingkat dari struktur data kompleks

• Atribut yang dihitung dalam node Inisiasi Atribut atau diproses melalui Logika node

Isi harus berupa JSON yang valid. Jika atribut yang dirujuk tidak ada atau bernilai null, null nilai null dikirim dalam JSON.

Bagaimana cara menguji konfigurasi Webhook saya?

Buka Penganalisis Data untuk aliran dan pilih perangkat pemicu. Cari atribut yang cocok dengan ID node ini: nilainya berubah menjadi 1 setiap kali Webhook dipicu, 0 jika tidak. Ini mengonfirmasi bahwa Webhook telah dipicu tanpa perlu akses ke endpoint tujuan.

Untuk memverifikasi bahwa tujuan benar-benar menerima payload yang diharapkan, pertimbangkan menggunakan layanan pengujian Webhook seperti webhook.site atau RequestBin selama pengembangan untuk memeriksa permintaan persis yang dikirim.