n8n ile Bağlantı Otomasyonu: Docker'dan Webhook'lara

Bağlantılar için self-hosted n8n otomasyonu, kontrol ettiğiniz sunucularda çalışan üç şey demektir: Docker'da bir n8n örneği, Elido webhook olaylarını alan herkese açık bir HTTPS uç noktası ve kapsamı sınırlı bir token ile Elido API'sine yapılan giden çağrılar. Bağlantı ve alan adı olayları imzalı gelir; tıklama başına olaylar yol haritasında. Sonrasında ne olacağına iş akışlarınız karar verir, yürütme günlükleri de altyapınızdan hiç çıkmaz.

Mimari bundan ibaret. Yazının geri kalanı, hızlı başlangıç kılavuzlarının atladığı kısım: webhook'ları bir ters vekil sunucudan nasıl geçireceğiniz, bir yabancının iş akışlarınızı tetikleyememesi için imzayı nasıl kontrol edeceğiniz, kuyruk modunun neyi değiştirdiği ve n8n Cloud'un dürüstçe ne zaman daha iyi bir seçim olduğu. Bu kurulumu tek bir küçük sanal makinede çalıştırıyorum ve tüm parçalar tek bir ekrana sığıyor.

Bağlantıların kendisinin de kendi donanımınızda durmasını istiyorsanız, o ayrı ve çok daha büyük bir iş. k3s üzerinde Elido self-hosting rehberi onu anlatıyor. Burada Elido yönetilen kalır, yalnızca otomasyon katmanı kuruma taşınır.

Bağlantı Otomasyonu için n8n'i Neden Kendiniz Barındırmalısınız

Genel neden veridir. Self-hosted bir n8n URL kısaltıcı iş akışı, işlediği her yükü görür: hedef URL'yi, etiketleri, bazen istediğinizden fazlasını söyleyen bir kampanya adını ve tıklama analitiğini içeri çekerseniz ülke, cihaz ve yönlendirenleri. n8n Cloud'da bu yürütmeler, başkasının saklama varsayılanlarıyla başkasının sunucularında tutulur. Self-hosted kurulumda ise sizin seçtiğiniz bölgedeki kendi Postgres'inizde durur.

GDPR'ın 28. maddesi uyarınca kişisel veriye dokunan her veri işleyenin bir sözleşmesi olmalı ve kayıtlarınızda yer almalıdır. Daha az veri işleyen, daha az evrak demektir. Pazarlama verileriniz zaten AB'de kalmak zorundaysa, AB veri yerleşimi rehberi otomasyon katmanının neden kısaltıcı kadar önemli olduğunu açıklıyor.

İkinci neden maliyetin şekli. n8n Cloud yürütme sayısına göre fiyatlandırır; yoğun bir webhook tetikleyicisi ya da sık yapılan bir analitik sorgusu yürütmeleri hızla tüketir. Self-hosted kurulumda bir yürütme, tabloda bir satır ve birkaç milisaniyelik işlemci süresidir.

Üçüncüsü erişim. Self-hosted bir örnek, CRM veritabanınızla ya da dahili bilet aracınızla aynı ağda durur; böylece bir bağlantı olayı, internete hiç açılmaması gereken bir sisteme düşebilir.

Docker Compose Yığını

Asgari bir n8n docker bağlantı otomasyonu yığını dört servis ister. Referans, n8n'in kendi Docker Compose rehberi; aşağıdaki, bağlantı işleri için başlangıç noktam olan sürüm; sonradan geçiş yapmak zorunda kalmamanız için kuyruk modu baştan açık.

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: ${PG_PASSWORD}
      POSTGRES_DB: n8n
    volumes: [pgdata:/var/lib/postgresql/data]

  redis:
    image: redis:7

  n8n:
    image: docker.n8n.io/n8nio/n8n
    env_file: .env.n8n
    ports: ["127.0.0.1:5678:5678"]
    depends_on: [postgres, redis]

  n8n-worker:
    image: docker.n8n.io/n8nio/n8n
    command: worker
    env_file: .env.n8n
    depends_on: [n8n]

volumes:
  pgdata:

Ve paylaşılan ortam dosyası:

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=change-me
EXECUTIONS_MODE=queue
QUEUE_BULL_REDIS_HOST=redis
N8N_ENCRYPTION_KEY=generate-a-long-random-string
N8N_WEBHOOK_URL=https://n8n.example.com/
N8N_PROXY_HOPS=1

İki satır göründüğünden daha önemli. Şifreleme anahtarı ana süreçte ve her işçide aynı olmalıdır; yoksa işçiler Elido kimlik bilgisini çözemez ve her yürütme kafa karıştırıcı bir yetkilendirme hatasıyla başarısız olur. Ayrıca 5678 portu yalnızca localhost'a bağlıdır, çünkü internete bakması gereken tek şey ters vekil sunucudur.

Self-Hosted n8n'den Elido API'sini Çağırma

Giden çağrılar için n8n'in kendi içinden gelenlerin ötesinde bir şeye gerek yok. Adı Authorization, değeri Bearer ve ardından Elido panosundan aldığınız bir API anahtarı olan bir Header Auth kimlik bilgisi oluşturun, sonra bunu yerleşik HTTP Request düğümünden kullanın. n8n bunu ortam dosyasındaki anahtarla diskte şifreler; bu anahtarın her yerde aynı olması gerektiğinin bir nedeni daha.

Her bağlantı rotası bir çalışma alanına bağlıdır. Bir URL'yi kısaltmak için https://api.elido.app/v1/workspaces/{workspace_id}/links adresine JSON gövdesiyle POST yapın:

{
  "domain_id": 12,
  "destination_url": "{{ $json.url }}",
  "title": "Spring launch",
  "tags": ["n8n", "spring"]
}

slug alanını bırakırsanız Elido bir tane üretir. domain_id, bağlantının yaşadığı kısa alan adıdır; /v1/workspaces/{workspace_id}/domains adresine yapılan bir GET sizinkileri listeler ve ben kimliği her çalıştırmada aramak yerine iş akışına sabit yazardım. Aynı bağlantı rotasına yapılan bir GET bağlantıları listeler, PATCH /v1/workspaces/{workspace_id}/links/{link_id} ise bir hedefi ya da etiketleri sonradan değiştirir.

POST'a, tetikleyen öğedeki sabit bir değerden (örneğin bir satır kimliğinden) üretilmiş bir Idempotency-Key başlığı ekleyin. n8n bir zaman aşımından sonra düğümü yeniden denerse API, ikinci bir bağlantı oluşturmak yerine ilk yanıtı tekrarlar. API ve SDK hızlı başlangıcı yüzeyin geri kalanını ele alıyor; ileride bir adımı koda taşımak isterseniz API ve SDK'lar sayfası da orada.

Bu çağrıları daha kullanışlı bir biçimde sarmalamayı hedefleyen, paketlenmiş bir topluluk düğümü de var: n8n-nodes-elido. npm'de yayımlandı (sürüm 0.2.0) ama hâlâ isteğe bağlı; doğrulanmış bir düğüm olmadığı için yalnızca self-hosted n8n'e kurulabilir, bu yazının zaten varsaydığı kurulum bu. HTTP Request sürümünü temel olarak tutun. Kuyruk modunda topluluk paketleri kurarsanız, arayüzün yalnızca ana kapsayıcıya kurduğunu, işçilerin bunu hiç görmediğini unutmayın. n8n 2.21'den itibaren ortam değişkeniyle kurulum yolu, başlangıçta her kapsayıcıyı eşitleyerek bunu çözer; ancak ilk seferde listesinde olmayan her şeyi kaldırır.

Elido Webhook'larını Ters Vekil Sunucunuzdan Geçirme

Olaylar ters yönde akar. Elido, Settings, Webhooks altında kaydettiğiniz bir uç noktaya link.created, link.updated ve domain.verified (ve diğerlerini) gönderir; self-hosted n8n'de bu uç nokta bir Webhook düğümünün üretim URL'sidir. Tıklama başına bir click.created olayı yol haritasında ama henüz yayında değil; bu yüzden şimdilik tıklama verisi, analitik API'sinden zamanlanmış bir çekmeyle gelir. Tam olay listesi ve yük şekilleri bağlantı olayları için webhook'lar referansında.

Bir vekil sunucunun arkasında n8n, webhook URL'sini kendi protokolünden, host'undan ve portundan kurar; yani soran herkese memnuniyetle http://localhost:5678/webhook/... adresini bildirir. Ters vekil sunucu yapılandırma sayfası kısa ve baştan sona okumaya değer: N8N_WEBHOOK_URL değerini herkese açık adresinize ayarlayın, N8N_PROXY_HOPS=1 yapın ve son vekil sunucunun X-Forwarded-For, X-Forwarded-Host ve X-Forwarded-Proto başlıklarını iletmesini sağlayın. Eski rehberler WEBHOOK_URL der; güncel sürümler onu hâlâ okur ama kullanımdan kaldırma uyarısı yazar.

Nginx, Traefik, hâlihazırda ne çalıştırıyorsanız olur. Önemli olan, herkese açık tarafta TLS olması ve /webhook/* yolunun n8n'e dokunulmadan ulaşmasıdır.

Bir zamanlama ayrıntısı canımı yaktı. Elido, bir teslimatı başarısız saymadan önce yanıt için on saniye bekler. Yavaş bir elektronik tablo API'sine yazıp sonra yanıt veren bir iş akışı bu süreyi aşabilir, yeniden denenir ve aynı satırı iki kez yazabilir. Webhook düğümünü hemen yanıt verecek şekilde ayarlayın ve işi sonradan yapın.

Bunu bir müşteri için kuruyorsanız ve webhook tarafının sizin yerinize halledilmesini istiyorsanız, webhook'lar özellik sayfası daha hiçbir şey kurmadan nelere abone olabileceğinizi gösteriyor.

Hiçbir Şey Çalışmadan Önce İmzayı Doğrulama

Herkese açık bir webhook URL'si, herkese açık bir URL'dir. Onu bulan herkes sahte bir olay POST'layıp iş akışınızı tetikleyebilir; bu yüzden tetikleyiciden sonraki ilk düğüm bir imza kontrolü olmalıdır.

Her Elido teslimatı X-Webhook-Signature (değer v1= artı onaltılık bir özet), Unix saniyesi cinsinden X-Webhook-Timestamp, X-Webhook-Event ve X-Webhook-Delivery taşır. Özet, zaman damgası, bir nokta ve ham istek gövdesi üzerinde HMAC-SHA256'dır; anahtar, uç noktayı oluşturduğunuzda bir kez gösterilen whsec_ sırrıdır.

Önce Webhook düğümünde Raw Body seçeneğini açın. İnsanların atladığı adım bu. Elido'nun gönderdiği tam baytlar yerine JSON.stringify($json.body) özetini alırsanız anahtar sırası ya da boşluklar farklı olur, her imza başarısız olur ve bir akşamı sırrın yanlış olduğuna ikna olarak geçirirsiniz. Ardından bir Code düğümü:

const crypto = require("crypto");
const item = $input.first();
const h = item.json.headers;
const raw = (await this.helpers.getBinaryDataBuffer(0, "data")).toString(
  "utf8",
);

const ts = Number(h["x-webhook-timestamp"]);
if (Math.abs(Date.now() / 1000 - ts) > 300) throw new Error("stale delivery");

const expected =
  "v1=" +
  crypto
    .createHmac("sha256", $env.ELIDO_WEBHOOK_SECRET)
    .update(`${ts}.${raw}`)
    .digest("hex");
const got = h["x-webhook-signature"] || "";
if (
  got.length !== expected.length ||
  !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
) {
  throw new Error("bad signature");
}
return [{ json: JSON.parse(raw) }];

crypto modülü Code düğümünde varsayılan olarak mevcuttur, dolayısıyla orada ek bir ayara gerek yok. Beş dakikalık pencere, yakalanmış bir isteğin yeniden oynatılmasını engeller. Sırrı döndürdüğünüzde Elido, geçiş döneminde ayrıca X-Elido-Signature-Previous gönderir; böylece değişkeni güncellerken iki anahtardan birini kabul edebilirsiniz. Webhook imza doğrulama rehberi, her iki başlığı da kontrol eden bir düğüm sürümünü ve aynı kontrolü Node, Python ve Go'da içeriyor.

Kuyruk Modu ve Yeniden Denemeler

İmza kontrolü yerindeyken geriye kalan soru, yük altında ya da bir şey çöktüğünde ne olacağı. Burada iki yeniden deneme sistemi devrede ve farklı hataları karşılıyorlar.

n8n kuyruk modunda ana süreç webhook'u alır, bir yürütme oluşturur ve kimliğini Redis'e verir; işçiler onu alır. Bir olay patlaması HTTP yanıtını durdurmak yerine kuyrukta birikir. Daha fazla gelen hacim için bir yük dengeleyicinin arkasına özel webhook işlemcileri ekleyebilirsiniz; ancak çoğu bağlantı iş yükünde bir ana süreç ve iki işçi fazlasıyla yeter.

Elido'nun tarafı, n8n'e ulaşılamaması durumunu karşılar. 2xx olmayan her yanıt ya da zaman aşımı 1, 5 ve 15 dakika sonra yeniden denenir; üç denemeden sonra teslimat başarısız işaretlenir ve panodan yeniden kurabilirsiniz. Bu, bir kapsayıcı yeniden başlatmasını ya da hızlı bir dağıtımı karşılar. Hafta sonu süren bir kesintiyi karşılamaz; bu yüzden webhook ve yoklama karşılaştırması yazısının savunduğu gibi webhook'ları, bağlantıları API üzerinden listeleyen gecelik bir mutabakatla eşleştirirdim.

X-Webhook-Delivery değerini bir idempotency anahtarı olarak kullanın. Yeniden denemeler onu yeniden kullanır.

Self-Hosted n8n ve n8n Cloud: Dürüst Ödünleşimler

Bunun için self-hosting'i tercih ediyorum ama pişman olan ekipler de gördüm. İşte iki tarafın da satış konuşması olmadan karşılaştırma.

Son satır iki yönlü işler. Küçük bir sanal makine ucuzdur, ama bozuk bir yükseltmeye giden bir mühendis saati ucuz değildir ve n8n sık sürüm çıkarır. Ekipte makinenin sahibi yoksa, HTTP Request düğümü ve Elido'nun REST API'siyle Cloud daha sağlıklı seçenektir; yönetilen yolun diğer platformlarda nasıl göründüğünü Make ve IFTTT tarifleri ya da Zapier rehberi gösteriyor.

Size söyleyemeyeceğim şey, veri koruma görevlinizin self-hosted bir makineyi bir tedarikçi DPA'sından daha basit bulup bulmayacağı. Deneyimime göre genelde bulurlar, ama bu makinenin ne kadar iyi işletildiğine bağlı. Sözleşmenin kısaltıcı tarafının nasıl işlediği için URL kısaltıcılar için GDPR rehberi başlangıç noktası. İlk iş akışını bağlamaya hazırsanız, bir çalışma alanında API token'ı alın ve bir Webhook düğümünü ona yönlendirin.

Blog'da İlgili Yazılar

• k3s üzerinde Elido self-hosting: rehber - bağlantıların da kurum içinde durması gerektiğinde.
• Bağlantı olayları için webhook'lar - her olay türü ve yük şekli.
• Tıklama takibi için webhook ve yoklama - gecelik mutabakat neden önemli.
• Make ve IFTTT ile kısa bağlantı otomasyonu - yönetilen düşük kodlu yol.
• n8n URL kısaltıcı - HTTP Request düğümü kurulumu ve üç iş akışı ayrıntılı.
• Webhook imzalarını doğrulama - ham gövde, yeniden oynatma penceresi ve sır döndürme, dört çalışma zamanında.