Blog

Webhook Servisleri ile Localhost API'lerini Test Etme

Ashley Innocent

Ashley Innocent

28 January 2026

Webhook Servisleri ile Localhost API'lerini Test Etme

Harici servislerden webhook veya geri arama (callback) alması gereken localhost API'lerini test etmek, yerel geliştirme sunucunuzu geçici olarak internete açmayı gerektirir. ngrok, NPort, Cloudflare Tunnel ve benzeri tünelleme hizmetleri, localhost'unuza herkese açık bir URL veren güvenli bağlantılar oluşturur.

💡
Bu rehberdeki webhook test iş akışlarını takip etmek için Apidog'u indirin. Bu rehber, doğru aracı nasıl seçeceğinizi, tünellemeyi nasıl kuracağınızı, Apidog kullanarak webhook'ları etkili bir şekilde nasıl test edeceğinizi ve kimlik doğrulama, hız sınırlamaları ve hata ayıklama gibi yaygın zorlukları nasıl yöneteceğinizi kapsar.
button

Neden Localhost Tünellemeye İhtiyacınız Var?

Üçüncü taraf hizmetlerle entegre olan bir API geliştiriyorsunuz. Dizüstü bilgisayarınızda her şey yolunda gidiyor; uç noktalar doğru yanıt veriyor, veriler sorunsuz akıyor. Ardından Stripe, GitHub, Twilio veya herhangi bir harici servisten gelen webhook geri aramalarını test etmeye çalışıyorsunuz.

Sorun: Harici servisler localhost:3000'e ulaşamıyor. Geliştirme sunucunuz internetten erişilebilir değil.

İş akışınızı bozan yaygın senaryolar:

1. Webhook Testi

Stripe gibi hizmetler ödeme onayları, GitHub depo etkinlikleri, Slack etkileşim etkinlikleri gönderir; bunların hepsi API'nize POST isteği olarak gelir. Geliştirme sırasında, bu hizmetlerin webhook göndermek için herkese açık bir URL'ye ihtiyacı vardır.

2. OAuth Geri Arama URL'leri

"Google ile oturum aç," "GitHub ile giriş yap," veya herhangi bir OAuth akışı uygularken, kimlik doğrulama sağlayıcısı kullanıcıları bir yetkilendirme koduyla uygulamanıza geri yönlendirir. Yönlendirme URL'si herkese açık olmalı ve sağlayıcıya kaydettiğinizle eşleşmelidir.

3. Üçüncü Taraf API Entegrasyonu

Bazı API'ler, asenkron işlemler için geri arama URL'leri gerektirir. Örneğin, video dönüştürme hizmetleri işlem tamamlandığında API'nizi bilgilendirir veya ödeme işlemcileri işlemleri onaylar.

4. Mobil Uygulama Geliştirme

API'nizi aynı ağdaki bir mobil cihazdan test etmek genellikle başarısız olur çünkü mobil uygulama localhost'u çözümleyemez. Bir tünel size herhangi bir cihazdan çalışan bir URL sağlar.

5. Müşteri Demoları

Bazen müşterilere veya paydaşlara devam eden işleri göstermeniz gerekebilir. Her küçük değişiklik için hazırlık ortamına dağıtım yapmak yinelemeyi yavaşlatır. Geçici bir herkese açık URL, müşterilerin geliştirme ortamınızı test etmesine olanak tanır.

Localhost Tünelleme Nasıl Çalışır?

Tünelleme hizmetleri, bulut sunucuları ile yerel makineniz arasında güvenli bir bağlantı oluşturur:

Harici Servis → Tünelleme Hizmeti (herkese açık URL) → Güvenli Bağlantı → Yerel Sunucunuz:3000

Süreç:

  1. Makinenizde yerel bağlantı noktanızı işaret eden bir tünel istemcisi başlatırsınız
  2. İstemci, tünelleme hizmetinin bulut altyapısına bağlanır
  3. Hizmet, herkese açık bir URL atar (örn. https://abc123.ngrok.io)
  4. Bu herkese açık URL'ye gelen istekler, şifreli bağlantı üzerinden localhost'unuza iletilir
  5. Yerel sunucunuz isteği doğrudan istemciden gelmiş gibi alır
  6. Yanıtlar tünel aracılığıyla istekte bulunana geri akar

Bu şeffaf bir şekilde gerçekleşir. Yerel sunucunuz, bir tünelin arkasında olduğunu bilmek zorunda değildir.

Popüler Tünelleme Hizmetlerini Karşılaştırma

İşte 2026'daki en popüler seçenekler, güçlü yönleri ve sınırlamalarıyla birlikte:

ngrok (En Popüler)

En iyisi: Köklü projeler, güvenilirlik isteyen ekipler

ngrok http 3000

Artıları:

Eksileri:

Ücretsiz Katman:

Ücretli Planlar: Aylık 8-20 dolar

NPort (Yükselen Ücretsiz Alternatif)

En iyisi: Abonelik maliyetlerinden kaçınan geliştiriciler

nport start 3000

Artıları:

Eksileri:

Ücretsiz Katman:

Bu, geliştiricilerin devam eden maliyetler olmadan ngrok alternatifleri arayışında Dev.to'da ilgi gören bir araçtır.

Cloudflare Tunnel (Üretime Yakın Kullanım İçin En İyisi)

En iyisi: Halihazırda Cloudflare kullanan ekipler, uzun süreli tüneller

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

Artıları:

Eksileri:

Ücretsiz Katman:

Localtunnel (En Basit)

En iyisi: Hızlı tek seferlik testler, kurulum gerektirmez

npx localtunnel --port 3000

Artıları:

Eksileri:

Ücretsiz Katman:

Tailscale Funnel (Ekipler İçin En İyisi)

En iyisi: Özel ekip paylaşımı, güvenli demolar

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

Artıları:

Eksileri:

Ücretsiz Katman:

Karşılaştırma Tablosu

ÖzellikngrokNPortCloudflare TunnelLocaltunnelTailscale
FiyatÜcretsiz/10$+ÜcretsizÜcretsizÜcretsizÜcretsiz/Ücretli
Oturum Sınırı2 saatYokYokYokYok
Özel Alan AdıÜcretliÜcretsizEvetHayırEvet
İstek DenetleyiciEvetTemelHayırHayırHayır
Kurulum KarmaşıklığıDüşükDüşükOrtaÇok DüşükOrta
GüvenilirlikMükemmelİyiMükemmelKötüMükemmel
En İyisiÜretim testiMaliyet odaklı geliştiricilerKurumsalHızlı testlerEkip paylaşımı

İlk Localhost Tünelinizi Kurma

En yaygın araçlarla kurulumu inceleyelim. Örnek olarak bir Node.js Express API kullanacağız, ancak bu, herhangi bir yerel sunucuyla çalışır.

Örnek: Yerel API Sunucusu

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

app.use(express.json());

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

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

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

Seçenek 1: ngrok Kullanımı

Adım 1: ngrok Kurulumu

# macOS
brew install ngrok

# Windows (via 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

Adım 2: Kimlik Doğrulama (isteğe bağlı ancak önerilir)

ngrok config add-authtoken YOUR_AUTH_TOKEN

Adım 3: Tüneli Başlatın

ngrok http 3000

Çıktı:

Session Status                online
Account                       you@example.com (Plan: Free)
Version                       3.5.0
Region                        United States (us)
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

API'nize artık https://abc123.ngrok.io adresinden erişilebilir.

Adım 4: Test Edin

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

Seçenek 2: NPort Kullanımı (Ücretsiz Alternatif)

Adım 1: NPort Kurulumu

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

Adım 2: Tüneli Başlatın

nport start 3000 --subdomain myapi

Çıktı:

✓ Tunnel started successfully
Public URL: https://myapi.nport.io
Local URL:  http://localhost:3000

Adım 3: Test Edin

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

Seçenek 3: Cloudflare Tunnel Kullanımı

Adım 1: cloudflared Kurulumu

# 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

Adım 2: Hızlı tünel (kayıt gerekmez)

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

Çıktı:

2026-01-27T12:00:00Z INF Your quick tunnel is: https://xyz789.trycloudflare.com

Kalıcı tüneller için (Cloudflare hesabı gerektirir):

# Login
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create myapi

# Configure and run
cloudflared tunnel --config config.yml run myapi

Apidog ile Webhook Testi

Artık localhost'unuz herkese açık olduğuna göre, Apidog kullanarak webhook'ları sistematik olarak test edelim.

Neden Tünellemeyi + Apidog'u Birleştirmeli?

Tünelleme erişimi çözer; Apidog doğrulamayı çözer:

Apidog'da Webhook Testi Kurulumu

Adım 1: API'nizi İçe Aktarın veya Oluşturun

  1. Apidog'u açın

2. Yeni bir proje oluşturun

3. Webhook uç noktanızı ekleyin:

Adım 2: Ortam Değişkenlerini Yapılandırın

İki ortam kurun:

Geliştirme (Tünellenmiş):

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

Üretim:

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

Bu, aynı uç noktayı yerel olarak ve üretimde tek tıklamayla test etmenizi sağlar.

Adım 3: Test Senaryoları Oluşturun

Webhook'lar geldiğinde ne olduğunu test edin:

Örnek: Stripe Ödeme Webhook Testi

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

Apidog'daki Doğrulamalar (Assertions):

  1. Durum kodu 200'e eşit
  2. Yanıt received: true içeriyor
  3. Yanıt süresi < 1000ms
  4. Content-Type application/json

Adım 4: Üçüncü Taraf Hizmetleri Simüle Edin

Stripe veya GitHub'dan gerçek webhook'ları tetiklemek yerine, bunları Apidog'da simüle edin:

  1. Servis dokümantasyonundan webhook payload örneklerini kopyalayın
  2. Çeşitli senaryolarla (başarı, hata, uç durumlar) test durumları oluşturun
  3. Tüm senaryoları tünellenmiş localhost'unuza karşı çalıştırın
  4. API'nizin her durumu doğru şekilde ele aldığını doğrulayın

OAuth Geri Aramalarını Test Etme

Senaryo: "Google ile Oturum Aç" özelliğini uyguluyorsunuz

Adım 1: Özel alt alan adıyla tüneli başlatın

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

Adım 2: Google Console'da OAuth yönlendirmesini yapılandırın

Geri arama URL'sini ayarlayın: https://myapp.ngrok.io/auth/google/callback

Adım 3: Akışı Apidog'da test edin

  1. Yetkilendirme URL'sini almak için /auth/google adresine istek gönderin
  2. Yönlendirmeyi manuel veya programatik olarak takip edin
  3. Geri aramanın yetkilendirme kodunu aldığını doğrulayın
  4. Token değişiminin doğru çalıştığını onaylayın

Adım 4: Token depolamasını doğrulayın

Apidog'u kullanarak:

Yaygın Kullanım Durumları

1. Ödeme Webhook'larını Test Etme (Stripe, PayPal)

Zorluk: Ödeme sağlayıcıları başarılı ödemeler, iadeler, anlaşmazlıklar gibi olaylar için webhook gönderir.

Çözüm:

# Start tunnel
ngrok http 3000

# Configure webhook URL in Stripe dashboard
# https://abc123.ngrok.io/webhook/stripe

# Use Stripe CLI to forward test webhooks
stripe listen --forward-to localhost:3000/webhook/stripe

# Trigger test events
stripe trigger payment_intent.succeeded

Apidog ile test edin:

2. Slack/Discord Bot Komutlarını Test Etme

Zorluk: Sohbet platformları, kullanıcılar düğmelere tıkladığında veya komutları çalıştırdığında etkileşim olayları gönderir.

Çözüm:

# Start tunnel
nport start 3000 --subdomain myslackbot

# Configure in Slack API:
# Interactivity URL: https://myslackbot.nport.io/slack/interactions
# Slash Commands: https://myslackbot.nport.io/slack/commands

Apidog ile test edin:

3. SMS/Sesli Webhook'larını Test Etme (Twilio)

Zorluk: Twilio, SMS geldiğinde veya sesli aramalar alındığında webhook gönderir.

Çözüm:

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

TwiML webhook'larını tünel URL'nize işaret edecek şekilde yapılandırın.

Apidog ile test edin:

4. Mobil Uygulama API Testi

Zorluk: API'nizi fiziksel bir cihazdan veya emülatörden test etme.

localhost ile ilgili sorun:

// This fails from mobile device
fetch('http://localhost:3000/api/users')

Tünel ile çözüm:

// This works from anywhere
fetch('https://myapi.ngrok.io/api/users')

Apidog ile test edin:

  1. Tünellenmiş temel URL ile API dokümantasyonu oluşturun
  2. Mobil ekiple paylaşın
  3. Mobil geliştiriciler canlı geliştirme sunucunuza karşı test yapabilir
  4. Hazır olduğunuzda hazırlık/üretim URL'lerine geçin

5. GitHub/GitLab Webhook'larını Test Etme

Zorluk: Depo webhook'larını (push, çekme isteği, sorunlar) yerel olarak test etme.

Çözüm:

# Start tunnel
ngrok http 4000

# Configure in GitHub repo settings:
# Webhook URL: https://abc123.ngrok.io/github/webhook
# Content type: application/json
# Events: Push, Pull requests

Apidog ile test edin:

Güvenlik En İyi Uygulamaları

Localhost'u internete açmak güvenlik riskleri oluşturur. Bu uygulamaları takip edin:

1. Yalnızca HTTPS Kullanın

Tüm tünelleme hizmetleri varsayılan olarak HTTPS sağlar. Tüneller için asla düz HTTP kullanmayın:

# Good
ngrok http 3000
# Creates https://abc123.ngrok.io

# Bad (don't do this)
ngrok http --scheme=http 3000

2. Webhook İmza Doğrulamasını Uygulayın

Gelen webhook'lara körü körüne güvenmeyin. İmzaları doğrulayın:

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');
  }

  // Process webhook
});

3. Temel Kimlik Doğrulama ile Erişimi Kısıtlayın

Tünelinize kimlik doğrulama ekleyin:

# ngrok with basic auth
ngrok http 3000 --auth="username:password"

# NPort with basic auth
nport start 3000 --auth username:password

Artık istekler kimlik bilgileri gerektirir:

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

4. Ortama Özgü Gizli Bilgiler Kullanın

Webhook gizli bilgilerini veya API anahtarlarını asla commit etmeyin:

// .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. Tünel Erişimini İzleyin

Şüpheli etkinlikleri izlemek için istek denetçisini kullanın:

# ngrok provides a web interface at:
http://localhost:4040

# View all requests, responses, replay attacks

6. Tünel Süresini Sınırla

Tünelleri süresiz olarak çalıştırmayın:

# Auto-expire tunnel after 1 hour
ngrok http 3000 --session-duration 1h

7. İstek Kaynaklarını Doğrulayın

Gelen IP adreslerini kontrol edin veya izin listeleri kullanın:

const allowedIPs = [
  '192.0.2.1',  // Stripe webhook IPs
  '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();
});

Yaygın Sorun Giderme

Sorun 1: Tünel URL'si Her Oturumda Değişiyor

Sorun: Ücretsiz ngrok tünelleri, her yeniden başlatmada değişen rastgele URL'ler kullanır. Eski URL ile yapılandırılmış webhook'lar çalışmaz.

Çözümler:

  1. Statik URL'ler için ücretli plan kullanın:
ngrok http 3000 --domain=myapp.ngrok.app
  1. Ücretsiz özel alt alan adları ile NPort'a geçin:
nport start 3000 --subdomain myapp
# Always https://myapp.nport.io
  1. Tünel başladığında webhook'ları API aracılığıyla programatik olarak güncelleyin

Sorun 2: Webhook'lar Zaman Aşımına Uğruyor

Sorun: Yerel sunucunuz yanıt vermek için çok uzun sürüyor. Slack gibi hizmetler 3 saniye içinde yanıt gerektirir.

Çözüm:

Asenkron olarak işleyin:

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

  // Process in background
  processWebhookAsync(req.body).catch(console.error);
});

async function processWebhookAsync(data) {
  // Do slow work here (database, external APIs, etc.)
  await heavyProcessing(data);
}

Apidog ile test senaryolarında agresif zaman aşımı limitleri belirleyerek zaman aşımını test edin.

Sorun 3: Tarayıcıdan Gelen CORS Hataları

Sorun: Tünel URL'sine istek gönderen ön uç, CORS hataları alıyor.

Çözüm:

CORS başlıklarını yapılandırın:

const cors = require('cors');

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

Sorun 4: Ücretsiz Katmanda Hız Sınırlaması

Sorun: Ücretsiz tünellerin bağlantı limitleri vardır (ngrok: dakikada 40).

Çözümler:

  1. Hızlı ateşlenen bireysel testler yerine Apidog'da toplu test istekleri yapın
  2. Farklı hizmetler için birden fazla tünel kullanın
  3. Yoğun test yapıyorsanız ücretli katmana yükseltin
  4. Cloudflare Tunnel veya NPort gibi sınırsız hizmetlere geçin

Sorun 5: Tünel Sık Sık Bağlantıyı Kesiyor

Sorun: Ağ dengesizliği tünel kopmalarına neden oluyor.

Çözüm:

Otomatik yeniden başlatma için systemd/pm2 kullanın:

# Create systemd service
sudo nano /etc/systemd/system/ngrok.service

[Unit]
Description=ngrok tunnel
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

Sorun 6: Belirli Bir Ağdan Tünele Ulaşılamıyor

Sorun: Kurumsal güvenlik duvarları veya kısıtlayıcı ağlar tünel trafiğini engelliyor.

Çözümler:

  1. Cloudflare Tunnel kullanın (nadiren engellenir)
  2. Size daha yakın bir tünel bölgesine geçin:
ngrok http 3000 --region eu
  1. Herkese açık tünel yerine özel ağ için Tailscale kullanın

Gelişmiş Desenler

Desen 1: Çok Portlu Tünelleme

Birden fazla hizmeti aynı anda yayınlayın:

# Terminal 1: API server
ngrok http 3000

# Terminal 2: Frontend dev server
ngrok http 3001

# Terminal 3: Webhook worker
ngrok http 3002

Veya ngrok yapılandırma dosyasını kullanın:

# ~/.ngrok2/ngrok.yml
tunnels:
  api:
    proto: http
    addr: 3000
  frontend:
    proto: http
    addr: 3001
  worker:
    proto: http
    addr: 3002

ngrok start --all

Desen 2: Tünel + Docker Compose

# docker-compose.yml
version: '3'
services:
  api:
    build: .
    ports:
      - "3000:3000"

  ngrok:
    image: ngrok/ngrok:latest
    command:
      - "http"
      - "api:3000"
    environment:
      NGROK_AUTHTOKEN: ${NGROK_AUTHTOKEN}

docker-compose up

Desen 3: Dinamik Tünel URL Enjeksiyonu

Uygulamanızı tünel URL'si ile otomatik olarak güncelleyin:

// start-tunnel.js
const ngrok = require('ngrok');
const fs = require('fs');

(async function() {
  const url = await ngrok.connect(3000);
  console.log(`Tunnel started: ${url}`);

  // Update .env file
  fs.appendFileSync('.env', `\nTUNNEL_URL=${url}\n`);

  // Update Stripe webhook
  await updateStripeWebhook(url);
})();

Desen 4: İstekleri Birden Fazla Ortama Yönlendirme

Aynı webhook'u geliştirme, hazırlık ve üretim ortamlarına karşı test edin:

// webhook-multiplexer.js
app.post('/webhook', async (req, res) => {
  const environments = [
    'http://localhost:3000',
    'https://staging.api.com',
    'https://api.yourapp.com'
  ];

  // Forward to all environments
  const results = await Promise.all(
    environments.map(env =>
      fetch(`${env}/webhook`, {
        method: 'POST',
        headers: req.headers,
        body: JSON.stringify(req.body)
      })
    )
  );

  res.json({ forwarded: results.length });
});

Sonuç

Webhook veya geri arama alan localhost API'lerini test etmek, her değişiklik için hazırlık ortamına dağıtım yapmayı gerektirmez. Tünelleme hizmetleri, harici hizmetlerin geliştirme ortamınıza ulaşmasına olanak tanıyan geçici herkese açık URL'ler oluşturur.

Herhangi bir aracın ücretsiz katmanıyla başlayın. Webhook testi iş akışınızın günlük bir parçası haline gelirse, statik URL'ler ve ek özellikler için ücretli planları değerlendirin. Ancak çoğu geliştirici için, ücretsiz tünelleme hizmetleri, Apidog'un API test yetenekleriyle birleştiğinde, localhost API'lerini etkili bir şekilde test etmek için gereken her şeyi sağlar.

button

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir