Cara Menguji API Localhost dengan Layanan Webhook

Menguji API localhost yang perlu menerima webhook atau callback dari layanan eksternal membutuhkan eksposur server pengembangan lokal Anda ke internet sementara. Layanan tunneling seperti ngrok, NPort, Cloudflare Tunnel, dan lainnya membuat koneksi aman yang memberikan URL publik pada localhost Anda.

Mengapa Anda Membutuhkan Tunneling Localhost

Anda sedang membangun API yang terintegrasi dengan layanan pihak ketiga. Semuanya berfungsi di laptop Anda—endpoint merespons dengan benar, data mengalir lancar. Kemudian Anda mencoba menguji callback webhook dari Stripe, GitHub, Twilio, atau layanan eksternal lainnya.

Masalah: Layanan eksternal tidak dapat menjangkau localhost:3000. Server pengembangan Anda tidak dapat diakses dari internet.

Skenario umum yang mengganggu alur kerja Anda:

1. Pengujian Webhook

Layanan seperti Stripe mengirimkan konfirmasi pembayaran, GitHub mengirimkan event repositori, Slack mengirimkan event interaksi—semuanya sebagai permintaan POST ke API Anda. Selama pengembangan, layanan ini memerlukan URL publik untuk mengirim webhook.

2. URL Callback OAuth

Saat mengimplementasikan "Masuk dengan Google," "Login dengan GitHub," atau alur OAuth apa pun, penyedia autentikasi mengarahkan ulang pengguna kembali ke aplikasi Anda dengan kode otorisasi. URL pengalihan harus dapat diakses secara publik dan cocok dengan yang Anda daftarkan pada penyedia.

3. Integrasi API Pihak Ketiga

Beberapa API memerlukan URL callback untuk operasi asinkron. Misalnya, layanan transcoding video memberi tahu API Anda ketika pemrosesan selesai, atau pemroses pembayaran mengkonfirmasi transaksi.

4. Pengembangan Aplikasi Seluler

Menguji API Anda dari perangkat seluler di jaringan yang sama seringkali gagal karena aplikasi seluler tidak dapat me-resolve localhost. Sebuah tunnel memberi Anda URL yang berfungsi dari perangkat mana pun.

5. Demo Klien

Terkadang Anda perlu menunjukkan pekerjaan yang sedang berjalan kepada klien atau pemangku kepentingan. Menerapkan ke staging untuk setiap perubahan kecil memperlambat iterasi. URL publik sementara memungkinkan klien menguji lingkungan pengembangan Anda.

Cara Kerja Tunneling Localhost

Layanan tunneling membuat koneksi aman antara server cloud mereka dan mesin lokal Anda:

Layanan Eksternal → Layanan Tunneling (URL publik) → Koneksi Aman → Localhost Anda:3000

Prosesnya:

1. Anda memulai klien tunnel di mesin Anda yang menunjuk ke port lokal Anda
2. Klien terhubung ke infrastruktur cloud layanan tunneling
3. Layanan menetapkan URL publik (misalnya, https://abc123.ngrok.io)
4. Permintaan masuk ke URL publik tersebut diteruskan melalui koneksi terenkripsi ke localhost Anda
5. Server lokal Anda menerima permintaan seolah-olah datang langsung dari klien
6. Respons mengalir kembali melalui tunnel ke pemohon

Ini terjadi secara transparan. Server lokal Anda tidak perlu tahu bahwa itu berada di belakang sebuah tunnel.

Membandingkan Layanan Tunneling Populer

Berikut adalah opsi paling populer pada tahun 2026, dengan kekuatan dan keterbatasannya:

ngrok (Paling Populer)

Terbaik untuk: Proyek yang sudah mapan, tim yang menginginkan keandalan

ngrok http 3000

Kelebihan:

• Standar industri dengan dokumentasi ekstensif
• UI web inspector untuk melihat semua permintaan
• Domain kustom pada paket berbayar
• Fungsionalitas replay permintaan
• Terminasi TLS

Kekurangan:

• Tingkat gratis memiliki batas sesi 2 jam
• URL acak pada tingkat gratis (berubah setiap sesi)
• Harga mulai dari $10/bulan untuk URL persisten

Tingkat Gratis:

• 1 agen online
• 40 koneksi/menit
• URL acak yang kedaluwarsa

Paket Berbayar: $8-$20/bulan

NPort (Alternatif Gratis yang Berkembang)

Terbaik untuk: Pengembang yang menghindari biaya berlangganan

nport start 3000

Kelebihan:

• Sepenuhnya gratis dan sumber terbuka
• Tidak ada batas waktu sesi
• Subdomain kustom tersedia
• Opsi self-hosted
• Set fitur mirip dengan tingkat gratis ngrok

Kekurangan:

• Komunitas yang lebih kecil (tutorial lebih sedikit)
• Kurang matang (diluncurkan 2025)
• Tidak ada dukungan komersial

Tingkat Gratis:

• Tunnel tanpa batas
• Tidak ada batas waktu
• Subdomain kustom

Ini adalah alat yang mendapatkan daya tarik di Dev.to karena pengembang mencari alternatif ngrok tanpa biaya berkelanjutan.

Cloudflare Tunnel (Terbaik untuk Lingkungan Mirip Produksi)

Terbaik untuk: Tim yang sudah menggunakan Cloudflare, tunnel jangka panjang

cloudflared tunnel --url http://localhost:3000

Kelebihan:

• Infrastruktur kelas enterprise
• Perlindungan DDoS disertakan
• Terintegrasi dengan Cloudflare Zero Trust
• Tidak ada batasan bandwidth
• Gratis untuk sebagian besar kasus penggunaan

Kekurangan:

• Pengaturan lebih kompleks
• Membutuhkan akun Cloudflare
• Terlalu berlebihan untuk pengujian webhook sederhana

Tingkat Gratis:

• Bandwidth tanpa batas
• Tunnel tanpa batas
• Perlindungan DDoS

Localtunnel (Paling Sederhana)

Terbaik untuk: Uji coba cepat sekali pakai, tanpa instalasi

npx localtunnel --port 3000

Kelebihan:

• Tidak perlu pendaftaran
• Konfigurasi nol
• Tanpa instalasi (berjalan melalui npx)
• Sumber terbuka

Kekurangan:

• Tidak dapat diandalkan (sering down)
• Tidak ada inspeksi permintaan
• Hanya URL acak
• Dokumentasi minimal

Tingkat Gratis:

• Semuanya gratis
• Tidak ada batasan fitur

Tailscale Funnel (Terbaik untuk Tim)

Terbaik untuk: Berbagi tim pribadi, demo aman

tailscale serve https / http://localhost:3000
tailscale funnel 443 on

Kelebihan:

• Berdasarkan WireGuard (cepat, aman)
• Pribadi secara default (hanya terlihat oleh jaringan Tailscale Anda)
• Dapat diekspos secara publik saat dibutuhkan
• Sangat baik untuk kolaborasi tim

Kekurangan:

• Membutuhkan pengaturan Tailscale
• Kurva pembelajaran yang lebih curam
• Dirancang terutama untuk jaringan pribadi

Tingkat Gratis:

• Hingga 100 perangkat
• Bandwidth tanpa batas

Tabel Perbandingan

Menyiapkan Tunnel Localhost Pertama Anda

Mari kita bahas pengaturan dengan alat yang paling umum. Kita akan menggunakan API Node.js Express sebagai contoh, tetapi ini berfungsi dengan server lokal apa pun.

Contoh: Server API Lokal

// server.js
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  console.log('Webhook diterima:', req.body);
  res.json({ received: true });
});

app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

app.listen(3000, () => {
  console.log('Server berjalan di http://localhost:3000');
});

Opsi 1: Menggunakan ngrok

Langkah 1: Instal ngrok

# macOS
brew install ngrok

# Windows (melalui Chocolatey)
choco install ngrok

# Linux
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
  echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list && \
  sudo apt update && sudo apt install ngrok

Langkah 2: Autentikasi (opsional namun direkomendasikan)

ngrok config add-authtoken YOUR_AUTH_TOKEN

Langkah 3: Mulai tunnel

ngrok http 3000

Output:

Status Sesi                 online
Akun                          you@example.com (Paket: Gratis)
Versi                         3.5.0
Wilayah                       Amerika Serikat (us)
Penerusan                     https://abc123.ngrok.io -> http://localhost:3000

API Anda sekarang dapat diakses di https://abc123.ngrok.io.

Langkah 4: Uji coba

curl https://abc123.ngrok.io/health
# {"status":"sehat"}

Opsi 2: Menggunakan NPort (Alternatif Gratis)

Langkah 1: Instal NPort

npm install -g nport-cli
# atau
curl -sSL https://nport.io/install.sh | bash

Langkah 2: Mulai tunnel

nport start 3000 --subdomain myapi

Output:

✓ Tunnel berhasil dimulai
URL Publik: https://myapi.nport.io
URL Lokal:  http://localhost:3000

Langkah 3: Uji coba

curl https://myapi.nport.io/health
# {"status":"sehat"}

Opsi 3: Menggunakan Cloudflare Tunnel

Langkah 1: Instal cloudflared

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

Langkah 2: Quick tunnel (tidak perlu pendaftaran)

cloudflared tunnel --url http://localhost:3000

Output:

2026-01-27T12:00:00Z INF Quick tunnel Anda adalah: https://xyz789.trycloudflare.com

Untuk tunnel persisten (membutuhkan akun Cloudflare):

# Login
cloudflared tunnel login

# Buat tunnel
cloudflared tunnel create myapi

# Konfigurasi dan jalankan
cloudflared tunnel --config config.yml run myapi

Menguji Webhook dengan Apidog

Sekarang localhost Anda dapat diakses secara publik, mari kita uji webhook secara sistematis menggunakan Apidog.

Mengapa Menggabungkan Tunneling + Apidog?

Tunneling menyelesaikan akses; Apidog menyelesaikan verifikasi:

• Layanan tunneling membuat localhost Anda dapat dijangkau
• Apidog menguji respons API Anda, memvalidasi data, mengotomatiskan skenario

Menyiapkan Pengujian Webhook di Apidog

Langkah 1: Impor atau Buat API Anda

1. Buka Apidog

2. Buat proyek baru

3. Tambahkan endpoint webhook Anda:

• Metode: POST
• URL: {{base_url}}/webhook
• Header: Content-Type: application/json

Langkah 2: Konfigurasi Variabel Lingkungan

Siapkan dua lingkungan:

Pengembangan (Tunneled):

{
  "base_url": "https://abc123.ngrok.io"
}

Produksi:

{
  "base_url": "https://api.yourapp.com"
}

Ini memungkinkan Anda menguji endpoint yang sama secara lokal dan di lingkungan produksi dengan satu klik.

Langkah 3: Buat Skenario Pengujian

Uji apa yang terjadi ketika webhook tiba:

Contoh: Pengujian Webhook Pembayaran Stripe

// Request Body
{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_test123",
      "amount": 2000,
      "currency": "usd",
      "status": "succeeded"
    }
  }
}

Asersi di Apidog:

1. Kode status sama dengan 200
2. Respons berisi received: true
3. Waktu respons < 1000ms
4. Content-Type adalah application/json

Langkah 4: Simulasikan Layanan Pihak Ketiga

Alih-alih memicu webhook nyata dari Stripe atau GitHub, simulasikan di Apidog:

1. Salin contoh payload webhook dari dokumentasi layanan
2. Buat kasus uji dengan berbagai skenario (berhasil, gagal, kasus batas)
3. Jalankan semua skenario terhadap localhost yang ditunnel
4. Verifikasi API Anda menangani setiap kasus dengan benar

Menguji Callback OAuth

Skenario: Anda mengimplementasikan "Masuk dengan Google"

Langkah 1: Mulai tunnel dengan subdomain kustom

ngrok http 3000 --subdomain myapp
# URL: https://myapp.ngrok.io

Langkah 2: Konfigurasi pengalihan OAuth di Google Console

Atur URL callback: https://myapp.ngrok.io/auth/google/callback

Langkah 3: Uji alur di Apidog

1. Buat permintaan ke /auth/google untuk mendapatkan URL otorisasi
2. Ikuti pengalihan secara manual atau terprogram
3. Verifikasi callback menerima kode otorisasi
4. Pastikan pertukaran token berfungsi dengan benar

Langkah 4: Validasi penyimpanan token

Gunakan Apidog untuk:

• Verifikasi token disimpan dengan aman
• Uji alur refresh token
• Pastikan token yang kedaluwarsa ditangani

Kasus Penggunaan Umum

1. Menguji Webhook Pembayaran (Stripe, PayPal)

Tantangan: Penyedia pembayaran mengirimkan webhook untuk event seperti tagihan berhasil, pengembalian dana, sengketa.

Solusi:

# Mulai tunnel
ngrok http 3000

# Konfigurasi URL webhook di dasbor Stripe
# https://abc123.ngrok.io/webhook/stripe

# Gunakan Stripe CLI untuk meneruskan webhook pengujian
stripe listen --forward-to localhost:3000/webhook/stripe

# Picu event pengujian
stripe trigger payment_intent.succeeded

Uji dengan Apidog:

• Buat kasus uji untuk setiap jenis event
• Verifikasi idempotensi (penanganan webhook duplikat)
• Uji verifikasi tanda tangan
• Pastikan pembaruan basis data terjadi dengan benar

2. Menguji Perintah Bot Slack/Discord

Tantangan: Platform obrolan mengirimkan event interaksi saat pengguna mengklik tombol atau menjalankan perintah.

Solusi:

# Mulai tunnel
nport start 3000 --subdomain myslackbot

# Konfigurasi di Slack API:
# URL Interaktivitas: https://myslackbot.nport.io/slack/interactions
# Perintah Slash: https://myslackbot.nport.io/slack/commands

Uji dengan Apidog:

• Simulasikan klik tombol
• Uji respons perintah slash
• Verifikasi waktu respons (Slack membutuhkan respons <3 detik)
• Uji respons tertunda dengan response_url

3. Menguji Webhook SMS/Suara (Twilio)

Tantangan: Twilio mengirimkan webhook saat SMS tiba atau panggilan suara diterima.

Solusi:

cloudflared tunnel --url http://localhost:3000

Konfigurasi webhook TwiML untuk menunjuk ke URL tunnel Anda.

Uji dengan Apidog:

• Mock payload SMS masuk
• Uji berbagai jenis pesan (MMS, SMS)
• Verifikasi validasi tanda tangan Twilio
• Uji pembuatan TwiML respons

4. Pengujian API Aplikasi Seluler

Tantangan: Menguji API Anda dari perangkat fisik atau emulator.

Masalah dengan localhost:

// Ini gagal dari perangkat seluler
fetch('http://localhost:3000/api/users')

Solusi dengan tunnel:

// Ini berfungsi dari mana saja
fetch('https://myapi.ngrok.io/api/users')

Uji dengan Apidog:

1. Buat dokumentasi API dengan URL dasar yang ditunnel
2. Bagikan dengan tim seluler
3. Pengembang seluler dapat menguji terhadap server pengembangan langsung Anda
4. Beralih ke URL staging/produksi saat siap

5. Menguji Webhook GitHub/GitLab

Tantangan: Menguji webhook repositori (push, pull request, issues) secara lokal.

Solusi:

# Mulai tunnel
ngrok http 4000

# Konfigurasi di pengaturan repo GitHub:
# URL Webhook: https://abc123.ngrok.io/github/webhook
# Tipe Konten: application/json
# Event: Push, Pull requests

Uji dengan Apidog:

• Simulasikan event push
• Uji event PR dibuka/ditutup
• Verifikasi validasi tanda tangan (X-Hub-Signature)
• Uji logika pemfilteran cabang

Praktik Terbaik Keamanan

Mengekspos localhost ke internet menimbulkan risiko keamanan. Ikuti praktik-praktik ini:

1. Gunakan HTTPS Saja

Semua layanan tunneling menyediakan HTTPS secara default. Jangan pernah menggunakan HTTP biasa untuk tunnel:

# Baik
ngrok http 3000
# Membuat https://abc123.ngrok.io

# Buruk (jangan lakukan ini)
ngrok http --scheme=http 3000

2. Implementasikan Verifikasi Tanda Tangan Webhook

Jangan percaya webhook masuk secara membabi buta. Verifikasi tanda tangan:

const crypto = require('crypto');

function verifyStripeSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhook/stripe', (req, res) => {
  const signature = req.headers['stripe-signature'];

  if (!verifyStripeSignature(req.body, signature, process.env.STRIPE_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Proses webhook
});

3. Batasi Akses dengan Autentikasi Dasar

Tambahkan autentikasi ke tunnel Anda:

# ngrok dengan autentikasi dasar
ngrok http 3000 --auth="username:password"

# NPort dengan autentikasi dasar
nport start 3000 --auth username:password

Sekarang permintaan membutuhkan kredensial:

curl -u username:password https://abc123.ngrok.io/webhook

4. Gunakan Rahasia Khusus Lingkungan

Jangan pernah melakukan commit rahasia webhook atau kunci API:

// .env.development
STRIPE_WEBHOOK_SECRET=whsec_test_abc123
WEBHOOK_TUNNEL_URL=https://abc123.ngrok.io

// .env.production
STRIPE_WEBHOOK_SECRET=whsec_live_xyz789
WEBHOOK_URL=https://api.yourapp.com

5. Pantau Akses Tunnel

Gunakan inspektur permintaan untuk mengawasi aktivitas mencurigakan:

# ngrok menyediakan antarmuka web di:
http://localhost:4040

# Lihat semua permintaan, respons, serangan replay

6. Batasi Durasi Tunnel

Jangan biarkan tunnel berjalan tanpa batas waktu:

# Tunnel akan otomatis kedaluwarsa setelah 1 jam
ngrok http 3000 --session-duration 1h

7. Validasi Sumber Permintaan

Periksa alamat IP masuk atau gunakan daftar izin:

const allowedIPs = [
  '192.0.2.1',  // IP webhook Stripe
  '198.51.100.0/24'
];

app.use('/webhook', (req, res, next) => {
  const clientIP = req.ip;

  if (!allowedIPs.includes(clientIP)) {
    return res.status(403).send('Forbidden');
  }

  next();
});

Memecahkan Masalah Umum

Masalah 1: URL Tunnel Berubah Setiap Sesi

Masalah: Tunnel ngrok gratis menggunakan URL acak yang berubah setiap kali dimulai ulang. Webhook yang dikonfigurasi dengan URL lama akan rusak.

Solusi:

1. Gunakan paket berbayar untuk URL statis:

ngrok http 3000 --domain=myapp.ngrok.app

1. Beralih ke NPort dengan subdomain kustom gratis:

nport start 3000 --subdomain myapp
# Selalu https://myapp.nport.io

1. Perbarui webhook secara terprogram melalui API saat tunnel dimulai

Masalah 2: Webhook Timeout

Masalah: Server lokal Anda membutuhkan waktu terlalu lama untuk merespons. Layanan seperti Slack memerlukan respons dalam waktu 3 detik.

Solusi:

Proses secara asinkron:

app.post('/webhook', async (req, res) => {
  // Akui segera
  res.json({ received: true });

  // Proses di latar belakang
  processWebhookAsync(req.body).catch(console.error);
});

async function processWebhookAsync(data) {
  // Lakukan pekerjaan lambat di sini (basis data, API eksternal, dll.)
  await heavyProcessing(data);
}

Uji timeout dengan Apidog dengan mengatur batas timeout yang agresif dalam skenario pengujian.

Masalah 3: Kesalahan CORS dari Browser

Masalah: Frontend membuat permintaan ke URL tunnel mendapatkan kesalahan CORS.

Solusi:

Konfigurasi header CORS:

const cors = require('cors');

app.use(cors({
  origin: [
    'http://localhost:3001',  // Server pengembangan frontend Anda
    'https://abc123.ngrok.io'  // URL tunnel Anda
  ],
  credentials: true
}));

Masalah 4: Pembatasan Tingkat pada Tingkat Gratis

Masalah: Tunnel gratis memiliki batasan koneksi (ngrok: 40/menit).

Solusi:

1. Permintaan uji batch di Apidog alih-alih tes individu yang cepat
2. Gunakan beberapa tunnel untuk layanan yang berbeda
3. Upgrade ke tingkat berbayar jika pengujian berat
4. Beralih ke layanan tak terbatas seperti Cloudflare Tunnel atau NPort

Masalah 5: Tunnel Sering Terputus

Masalah: Ketidakstabilan jaringan menyebabkan tunnel terputus.

Solusi:

Gunakan systemd/pm2 untuk memulai ulang secara otomatis:

# Buat layanan systemd
sudo nano /etc/systemd/system/ngrok.service

[Unit]
Description=tunnel ngrok
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser
ExecStart=/usr/local/bin/ngrok http 3000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable ngrok
sudo systemctl start ngrok

Masalah 6: Tidak Dapat Menjangkau Tunnel dari Jaringan Tertentu

Masalah: Firewall perusahaan atau jaringan terbatas memblokir lalu lintas tunnel.

Solusi:

1. Gunakan Cloudflare Tunnel (jarang diblokir)
2. Ubah wilayah tunnel lebih dekat ke Anda:

ngrok http 3000 --region eu

1. Gunakan Tailscale untuk jaringan pribadi alih-alih tunnel publik

Pola Tingkat Lanjut

Pola 1: Tunneling Multi-Port

Ekspos beberapa layanan secara bersamaan:

# Terminal 1: Server API
ngrok http 3000

# Terminal 2: Server pengembangan frontend
ngrok http 3001

# Terminal 3: Pekerja Webhook
ngrok http 3002

Atau gunakan file konfigurasi ngrok: