Webhook n8n: Cara Menerima Data dari Aplikasi Lain

Webhook di n8n adalah alamat URL khusus yang membuat workflow Anda langsung jalan setiap kali aplikasi lain mengirim data ke alamat itu. Contohnya: begitu pelanggan membayar, payment gateway mengirim kabar ke webhook n8n, lalu n8n mengubah status invoice jadi lunas dan memberi tahu tim finance. Tidak ada yang perlu cek mutasi manual.

Kalau konsep webhook-nya sendiri masih asing, baca dulu webhook adalah. Artikel ini fokus ke praktiknya di n8n: cara memasang node Webhook, mengamankannya, merespons pengirim dengan benar, dan mencari tahu kenapa webhook tidak terpanggil.

Webhook node: test URL vs production URL

Saat Anda menambahkan node Webhook sebagai trigger, n8n langsung membuat dua alamat:

Test URL: dipakai saat Anda membangun workflow. Alamatnya mengandung /webhook-test/. URL ini hanya aktif saat Anda klik “Listen for test event” atau menjalankan workflow dari editor. Data yang masuk langsung tampil di layar, jadi Anda bisa melihat strukturnya.
Production URL: dipakai untuk pemakaian sungguhan. Alamatnya mengandung /webhook/. URL ini baru aktif setelah workflow di-publish. Data yang masuk tidak tampil di editor, tapi bisa dilihat di tab Executions.

Pengaturan lain yang perlu Anda isi:

HTTP Method: sesuaikan dengan yang dikirim aplikasi sumber. Kebanyakan notifikasi memakai POST.
Path: bagian akhir URL. Ganti ID acak bawaan dengan nama yang jelas, misalnya pembayaran-masuk, supaya mudah dikenali.
Authentication: pilihan Basic auth, Header auth, JWT auth, atau None. Kita bahas di bagian berikutnya.
Respond: kapan dan bagaimana n8n membalas pengirim.

Kesalahan paling umum pemula adalah mendaftarkan test URL ke aplikasi sumber, lalu heran kenapa workflow tidak jalan keesokan harinya. Test URL hanya mendengarkan saat Anda sedang menguji. Setelah selesai, ganti dengan production URL dan pastikan workflow sudah di-publish.

Kalau Anda baru mulai memakai n8n, panduan belajar n8n dari nol membahas dasar-dasar node dan trigger yang dipakai di sini.

Mengamankan webhook dengan header dan token

Production URL bisa dipanggil oleh siapa saja yang tahu alamatnya. Tanpa pengaman, orang iseng bisa mengirim data palsu, misalnya “pembayaran INV-0231 sudah lunas”. Karena itu webhook yang memicu proses penting harus diverifikasi.

Beberapa cara yang bisa dipakai, dari yang paling sederhana:

Header auth: aplikasi pengirim menyertakan header rahasia, misalnya X-Api-Key: <token>. Di n8n, pilih Header auth, buat kredensial dengan nama header dan nilainya. Request tanpa header yang cocok akan ditolak otomatis.
Token dari aplikasi sumber: banyak aplikasi sudah punya mekanisme sendiri. Xendit, misalnya, menyertakan token verifikasi di header x-callback-token. Midtrans menyertakan signature_key di body notifikasi yang bisa Anda hitung ulang dan cocokkan. Cek dokumentasi aplikasi yang Anda pakai.
Basic auth atau JWT: cocok kalau pengirimnya aplikasi buatan tim Anda sendiri.
Batasi IP pengirim: di Options node Webhook ada pengaturan untuk hanya menerima IP tertentu. Berguna kalau vendor mempublikasikan daftar IP server mereka.

Untuk token yang harus dicocokkan manual (seperti signature Midtrans), taruh node IF atau Code tepat setelah Webhook. Kalau tidak cocok, hentikan workflow dan catat percobaannya.

Satu lagi: jangan pernah mempercayai isi webhook mentah-mentah untuk hal yang menyangkut uang. Kalau bisa, cek ulang status transaksi ke API payment gateway sebelum mengubah invoice jadi lunas.

Merespons pengirim dengan cepat

Aplikasi yang mengirim webhook biasanya menunggu balasan. Kalau balasannya lama atau bukan kode sukses (2xx), banyak aplikasi menganggap pengiriman gagal lalu mengirim ulang. Akibatnya workflow bisa jalan dua kali untuk kejadian yang sama.

n8n punya beberapa pilihan di pengaturan Respond:

Pilihan	Kapan n8n membalas	Cocok untuk
Immediately	Begitu data diterima	Proses yang lama atau tidak perlu memberi hasil ke pengirim
When Last Node Finishes	Setelah seluruh workflow selesai	Workflow singkat yang hasilnya dibutuhkan pengirim
Using ‘Respond to Webhook’ Node	Saat node Respond to Webhook dijalankan	Anda ingin mengatur isi dan kode balasan sendiri

Aturan praktisnya: kalau prosesnya cuma beberapa detik, balas setelah selesai. Kalau prosesnya panjang (membuat PDF, memanggil AI, mengirim banyak email), balas secepatnya lalu lanjutkan proses di belakang. Dengan node Respond to Webhook, Anda bahkan bisa membalas 401 kalau token tidak valid dan 200 kalau semuanya beres.

Karena pengiriman ulang tetap mungkin terjadi, buat workflow Anda idempoten: aman dijalankan dua kali. Caranya, cek dulu apakah ID transaksi itu sudah pernah diproses sebelum mengubah data.

Contoh: pembayaran masuk memicu invoice lunas

Misalnya sebuah agensi mencatat invoice di Google Sheets dan menerima pembayaran lewat payment gateway. Alurnya:

Payment gateway mengirim POST ke production URL n8n saat pembayaran berhasil.
n8n memeriksa token di header. Kalau tidak cocok, workflow berhenti.
n8n mengambil nomor invoice dari data yang masuk dan mencarinya di spreadsheet.
Status invoice diubah menjadi “Lunas”, lengkap dengan tanggal dan nominal.
n8n membalas 200 OK ke payment gateway.
Setelah itu, n8n bisa mengirim email tanda terima ke klien dan notifikasi ke tim finance.

Diagram sequence webhook n8n: aplikasi sumber mengirim POST ke webhook n8n, n8n mengecek token di header, mencari nomor invoice, mengubah status jadi lunas di Google Sheets, lalu membalas 200 OK ke pengirim

Tanpa webhook, tim finance harus membuka dashboard payment gateway, mencocokkan pembayaran satu per satu dengan spreadsheet, lalu mengirim konfirmasi manual. Dengan webhook, semua itu terjadi dalam hitungan detik setelah pelanggan membayar. Ide serupa bisa Anda lihat di bagian contoh penerapan.

Debugging webhook yang tidak terpanggil

Kalau aplikasi sumber bilang sudah mengirim tapi workflow tidak jalan, cek hal-hal ini berurutan:

URL yang didaftarkan: apakah masih test URL (/webhook-test/)? Ganti ke production URL.
Status workflow: apakah sudah di-publish? Production URL tidak aktif sebelum itu.
HTTP method: aplikasi mengirim POST tapi node diatur GET, atau sebaliknya.
Tab Executions: kalau ada eksekusi yang gagal, penyebabnya ada di situ. Kalau tidak ada eksekusi sama sekali, request belum sampai ke n8n.
Alamat server (self-hosted): kalau n8n dipasang di server sendiri di balik reverse proxy, pastikan variabel WEBHOOK_URL diisi domain publik. Kalau tidak, URL yang tampil di editor bisa berupa localhost yang tidak bisa diakses dari luar.
Log pengiriman di aplikasi sumber: banyak aplikasi mencatat kode balasan dari setiap webhook. Kode 404 biasanya berarti path salah atau workflow belum aktif. Kode 401 atau 403 berarti autentikasi tidak cocok.
Uji manual: kirim request sendiri memakai curl atau Postman ke URL yang sama. Kalau ini berhasil, masalahnya ada di sisi pengirim.

Tambahkan juga notifikasi error, misalnya lewat Error Trigger, supaya Anda tahu kalau ada eksekusi yang gagal sebelum pelanggan komplain.

Kalau Anda ingin memastikan webhook untuk proses penting seperti pembayaran berjalan aman dan tidak dobel, Aqilatic bisa membantu meninjau alurnya lewat audit proses gratis.

Pertanyaan yang sering muncul

Apakah webhook n8n bisa dipakai di n8n Cloud?

Bisa. n8n Cloud memberi Anda domain publik, jadi production URL langsung bisa dipanggil dari aplikasi lain tanpa pengaturan server.

Berapa ukuran maksimal data yang bisa diterima webhook n8n?

Menurut dokumentasi n8n, batas bawaannya 16 MB per request. Di versi self-hosted, batas ini bisa diubah lewat variabel N8N_PAYLOAD_SIZE_MAX.

Apakah satu workflow bisa punya beberapa webhook?

Bisa, dengan menambahkan beberapa node Webhook dengan path berbeda. Tapi biasanya lebih rapi memisahkan satu workflow untuk satu jenis kejadian.