IP değişiklik olayları için webhook'lar — bir tünel döndüğü anda bildirim alın

API'yi "proxy'min IP'si değişti mi?" diye sürekli sorgulamak işe yarar, ancak her iki tarafta da döngü harcar ve aşağı yöndeki her iş akışına gecikme ekler. Webhook'lar bu modeli tamamen tersine çevirir: Nodetonet'e tek bir HTTPS uç noktası söylersiniz ve tünellerinizden biri çıkış IP'sini değiştirdiği anda imzalı küçük bir JSON yükü oraya iletilir — sorgulama yok, gecikme yok, kaçırılan olay yok. Bu rehber; kayıt, olayı tetikleyen üç senaryo, yük yapısı, HMAC imza doğrulaması, yeniden deneme davranışı ve canlıya geçmeden önce tüm hattı yerel olarak nasıl test edeceğinizi anlatır.

Kısa özet: /webhooks'a bir URL kaydedin, proxy.ip_changed'i dinleyin, X-Nodetonet-Signature başlığını doğrulayın ve kararlı id alanıyla yinelenenleri elemek için deduplicate uygulayın. Tümü aşağıda adım adım açıklanıyor.

Neden sorgulamak yerine webhook?

Bir sorgu döngüsü IP'nin ne sıklıkla değişeceğini tahmin etmek zorundadır. Aralığı çok kısa tutarsanız istek kotasını boşa harcarsınız; çok uzun tutarsanız aşağı yöndeki mantığınız eski veriye göre çalışır. Farklı havuzların farklı zamanlamalarla döndüğü onlarca token grubu yönetiyorsanız sorunlar katlanır. Webhook'lar bunu temiz çözer — IP değişikliğinden saniyeler içinde bir olay alırsınız; bu değişimin sticky oturum TTL'inden, manuel istekten ya da cihazda gerçek bir operatör olayından kaynaklanması fark etmez.

Bu; her yeni çıkış IP'sini kaydetmesi gereken hesap yönetimi iş akışlarında, operatör NAT yeniden atamalarını izleyen bir izleme panosunda veya havuz üyesinin adresi değiştiğinde bilmesi gereken bir yük dengeleyicide en çok işe yarar.

Webhook kaydetme

Panelde /webhooks'i açın ve + New webhook'a tıklayın. Üç şey girersiniz:

• Bir URL — HTTPS olmalı. Kaydedince bir HEAD prob göndeririz; sunucunuz 5 saniye içinde yanıt vermezse kayıt başarısız olur.
• Bir olay filtresi — bu kullanım durumu için proxy.ip_changed'i seçin. Tam olay kataloğu /documents'tadır.
• İsteğe bağlı bir proxy filtresi — varsayılan olarak hesabınızdaki her proxy için tetikleriz. Yalnızca belirli bir havuzla ilgileniyorsanız bir veya birden fazla proxy ID'siyle kapsamı daraltın.

Kaydettikten sonra panel bir imzalama sırrı (signing secret) döner. Buna şifre gibi davranın — ortam değişkeninde saklayın, asla kaynak koduna yazmayın. Her gelen isteği doğrulamak için kullanacaksınız.

Üç tetikleyici

proxy.ip_changed üç farklı koşulda tetiklenir. Yükteki reason alanı hangisinin gerçekleştiğini söyler:

device_reconnect tetikleyicisi yalnızca mobil proxy'lere özgüdür — datacenter ve upstream residential havuzlar onu hiçbir zaman tetiklemez. Gerçek bir hücresel cihazın doğal IP çalkantısını izlemek ve aşağı yöndeki oturumunuzun yeniden kimlik doğrulaması gerekip gerekmediğine karar vermek için özellikle yararlıdır.

Yük yapısı

Her proxy.ip_changed olayı aynı JSON zarfını kullanır:

{
  "event": "proxy.ip_changed",
  "id": "evt_9k2x7m",
  "timestamp": "2026-04-04T11:08:42.331Z",
  "data": {
    "proxyId": "prx_4d7a91",
    "oldIp": "188.114.96.7",
    "newIp": "92.184.117.42",
    "reason": "device_reconnect",
    "tokenId": "tok_3kzl8w9"
  }
}

Her teslimdeki standart başlıklar:

Content-Type: application/json
User-Agent: Nodetonet-Webhooks/1.0
X-Nodetonet-Event: proxy.ip_changed
X-Nodetonet-Event-Id: evt_9k2x7m
X-Nodetonet-Signature: t=1712228922,v1=4f8c...e3a1

tokenId, isteğe hizmet eden cihaz havuzunu çapraz referanslar — tek bir proxy ID'si birden fazla token grubuna eşleniyorsa kullanışlıdır. Tam denetim izleri için proxyId ve tokenId'yi birlikte kaydedin.

HMAC imza doğrulaması

X-Nodetonet-Signature başlığı sizi sahte teslimlere karşı korur. Kayıt sırasında aldığınız imzalama sırrını kullanarak "timestamp.rawBody" dizesi üzerinde hesaplanan bir Unix zaman damgası ve HMAC-SHA256 imzası içerir.

Node.js'te doğrulama — 15 satırın altında:

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const [tPart, vPart] = signatureHeader.split(',');
  const t = tPart.split('=')[1];
  const sig = vPart.split('=')[1];

  // Replay saldırılarını engellemek için 5 dakikadan eski olayları reddet
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(t + '.' + rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(sig, 'hex'),
  );
}

Kaçınılması gereken iki yaygın hata: Birincisi, yeniden serileştirilmiş bir JSON nesnesi değil, ham istek gövdesini geçin — boşluk farkları imzayı bozar. Express'te webhook rotanızda JSON middleware'inden önce express.raw({ type: 'application/json' }) kullanın. İkincisi, 5 dakikalık pencere isteğe bağlı değildir — geçerli imzalı bir teslimi yakalayıp daha sonra uç noktanıza yeniden gönderdiği replay saldırılarını önler.

Başarısızlıkta yeniden deneme zamanlaması

Uç noktanız 5xx durum kodu dönerse — ya da 10 saniye içinde yanıt vermezse — üstel geri alma ile yeniden deneriz:

Deneme 1: hemen
Deneme 2: +30 sn
Deneme 3: +2 dak
Deneme 4: +15 dak
Deneme 5: +1 saat
Deneme 6: +6 saat
24 saat sonra bırakılır

4xx yanıt, bilinçli bir ret olarak değerlendirilir — bozuk imza, yanlış içerik türü, tanınmayan olay — ve yeniden denemeyiz. Uç noktanız geçici olarak bozuksa (dağıtım penceresi, çökme) 500 veya 503 döndürün; geri geleceğiz.

Idempotency anahtarı: her olay kararlı bir id alanı taşır (örn. evt_9k2x7m). Yeniden denemeler aynı ID'yi korur, bu yüzden işleyiciniz onu deduplicate etmelidir. En basit yöntem: id'yi benzersiz kısıtlamalı bir veritabanı sütununa yazın ve insert çakışmalarını sessizce yoksayın.

Canlıya geçmeden yerel test

Panel, her kayıtlı webhook'un yanında bir Send test event düğmesi içerir. Tıklayın; gerçekçi görünen verilerle ve gerçek bir HMAC imzasıyla yapay bir proxy.ip_changed olayı göndeririz — tam doğrulama ve işleyici mantığınızı çalıştırmak için yeterlidir.

Yerel bir geliştirme sunucusuna karşı test almak için yerel bir portu kamuya açın. Yaygın seçenekler:

• ngrok http 3000 — yerel portunuza tünel kuran genel bir HTTPS URL'si üretir. İki aracı farklı görevler için ne zaman tercih edeceğinize dair bağlam için Nodetonet vs ngrok karşılaştırmasına bakın.
• Nodetonet'in kendi HTTP tünelleri — bir Windows .exe ajanı veya mobil cihaz token'ı eşleştirin ve ayrı bir araç olmadan kalıcı bir subdomain edinin.

Uç noktayı üretimde kaydetmeden önce işleyicinizin ayrıştırılmış yükü ve imza doğrulama sonucunu kaydettiğini doğrulayın. Ham-gövde ayrıştırma hatasını geliştirme aşamasında yakalamak, üretim günlüklerinden tanılamaktan çok daha ucuzdur.

Bütünü bir araya getirme — minimal Express işleyici

Aşağıda tam, üretime hazır bir webhook alıcısı yer alıyor. İmzayı doğrular, olay ID'siyle deduplicate eder ve geçişi aşağı yönlü kullanım için kaydeder:

const express = require('express');
const crypto  = require('crypto');
const app     = express();

const SECRET = process.env.NODETONET_WEBHOOK_SECRET;
const seen   = new Set(); // üretimde DB benzersiz kısıtlamasıyla değiştirin

app.post('/hooks/ip-changed',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['x-nodetonet-signature'];
    if (!verifyWebhook(req.body.toString(), sig, SECRET)) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body);
    if (seen.has(event.id)) return res.sendStatus(200); // dedupe
    seen.add(event.id);
    const { proxyId, oldIp, newIp, reason } = event.data;
    console.log('IP döndü:', proxyId, oldIp, '->', newIp, '(' + reason + ')');
    // aşağı yönlü mantığınız buraya
    res.sendStatus(200);
  },
);

app.listen(3000);

express.raw'ın yalnızca bu tek rotaya uygulandığına dikkat edin — diğer rotalarınız JSON'ı normal şekilde ayrıştırmaya devam edebilir. 10 saniyelik teslimat zaman aşımını hiçbir zaman ihlal etmemek için olayı kabul eder kabul etmez 200 ile yanıt verin; yavaş işlemleri asenkron yapın.

IP değişikliği olayıyla ne yapılır

Olay, diğer Nodetonet özellikleriyle birleştirildiğinde en güçlü hale gelir:

• Her IP geçişini kaydedin — uyumluluk veya hata ayıklama için (proxyId, eskiIp, yeniIp, neden, zaman) içeren bir denetim tablosu tutun. Döndürme anında operatör ve coğrafi meta verileri yakalamak için her newIp'de ücretsiz IP adresim nedir araçımızı çalıştırın.
• Oturumları yeniden doğrulayın — scraper'ınız eski IP'ye bağlı oturum açık bir oturum tutuyorsa, sonraki istekte kırık bir oturumla karşılaşmak yerine olayı bir sonraki istekten önce yeniden giriş için sinyal olarak kullanın.
• Proxy sağlık kontrolü tetikleyin — bir device_reconnect'in ardından yeni IP'nin rotasyon havuzunuza eklenmeden önce temiz olduğunu onaylamak için proxy denetleyicimizi çağırın.
• Trafiği akıllıca yönlendirin — operatör IP'si temiz olarak onaylandıktan sonra yeni isteklerin backconnect uç noktasına gitmesi için bir yönlendirme tablosunu güncelleyin.

Tam otomatik boru hattı oluşturma için Python'da programatik tünel oluşturma'ya bakın — webhook, IP döndürme ile orkestrasyon kodunuz arasındaki geri bildirim döngüsünü kapatarak o rehberi tamamlar.

Sırada ne var

• İlk REST API çağrınız — bu yazının üzerine kurulduğu kimlik doğrulama ve istek temelleri.
• Sticky oturumlar açıklandı — reason: "sticky_ttl"'nin tam olarak ne zaman ve neden tetiklendiğini ve iş yükünüze göre TTL'yi nasıl ayarlayacağınızı anlayın.
• Rotating mobil proxy ne zaman kullanılır — her iş için istek başına taze IP mi yoksa sabitlenmiş oturum mu gerektiğine karar verin.
• Token grupları ve cihaz havuzları — webhook'larınızın aldığı IP değişikliği olaylarını üreten filolari yönetin.
• Ücretsiz hesap oluşturun ve ilk webhook'unuzu dakikalar içinde kaydedin.