Webhook'lar: bağlantı ve tıklama olaylarına abone olun

Webhook'lar, olayları Elido'dan sunucunuza gerçekleştikleri anda gönderir. Gerçek zamanlı veriye ihtiyaç duyduğunuzda API'yi yoklamak yerine bunları kullanın — tipik kullanım örnekleri arasında bağlantı meta verilerini CRM'inizle senkronize etmek, özel bir kontrol paneli oluşturmak veya bir bağlantı yayınlandığında bir CI hattını başlatmak yer alır.

Bir webhook uç noktası ekleyin

1. Kontrol Paneli → Webhook'lar → Yeni uç nokta.
2. POST yapmamız gereken URL'yi yapıştırın. HTTPS olmalıdır — düz HTTP'yi oluşturma anında reddederiz.
3. İstediğiniz olay türlerini seçin. Tam liste aşağıdadır.
4. (İsteğe bağlı) Bir imzalama gizli anahtarı yapıştırın veya birini bizim oluşturmamıza izin verin. Gizli anahtar bir kez gösterilir; sayfadan ayrılmadan önce kopyalayın.
5. Kaydet. Uç noktanın erişilebilir olduğunu doğrulayabilmeniz için hemen bir test olayı göndeririz.

Olay kataloğu

Mevcut olay türleri. İsimler <kaynak>.<eylem> formatını izler ve sürümler arasında sabit kalır.

• link.created — yeni bir kısa bağlantı oluşturuldu.
• link.updated — hedef, slug, son kullanma tarihi veya şifre değişti.
• link.deleted — bağlantı yumuşak silindi (30 gün boyunca hâlâ kurtarılabilir).
• link.clicked.aggregated — her 60 saniyede bir, önceki pencere için bağlantı başına tıklama sayılarını göndeririz. Tıklama başına olayları webhook'lar üzerinden teslim etmeyiz (hacim çoğu uç noktayı ezerdi) — ham olay verisi için tıklama dışa aktarımını kullanın.
• domain.verified — özel bir alan adının DNS kontrolü geçti.
• domain.tls_renewed — Caddy, özel bir alan adı için TLS sertifikasını yeniledi.
• qr.generated — bir QR kod SVG/PNG'si oluşturuldu.
• abuse.flagged — URL tarayıcımız bir hedefi şüpheli olarak işaretledi.
• member.invited / member.removed — çalışma alanı üyelik değişiklikleri.

Yük şekli

Her olay aynı zarfa sahiptir:

{
  "id": "evt_2c8L9N4M5",
  "type": "link.created",
  "created_at": "2026-05-15T09:42:11.382Z",
  "workspace_id": 4123,
  "data": {
    "link_id": 891234,
    "slug": "spring-2026",
    "destination": "https://acme.com/spring-sale",
    "created_by": "user_5821"
  }
}

id, teslimat başına benzersizdir. Bunu bir teklik (idempotency) için kullanın — aynı id'yi iki kez alırsanız (yeniden denediğimiz için), yinelenenleri atlayın.

İmzaları doğrulama

Her webhook gövdesini, uç noktanızın gizli anahtarını kullanarak HMAC-SHA256 ile imzalarız. İmza, Elido-Signature başlığında t=<unix_ts>,v1=<hex> biçiminde bulunur.

Node'da doğrulamak için:

import { createHmac } from "node:crypto";

function verify(secret: string, body: string, header: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");
  return expected === parts.v1;
}

Yeniden denemeler

Başarısız teslimatları (herhangi bir 2xx dışı yanıt veya 10 saniye içinde yanıt yok) üstel geri çekilmeyle yeniden deneriz: 30s, 1m, 5m, 30m, 2h, 12h. 6 başarısızlıktan sonra uç noktayı başarısız olarak işaretleriz ve o belirli olayı yeniden denemeyi durdururuz. Uç nokta abone kalır; yeni olaylar teslim edilmeye devam eder.

Uç nokta 5 art arda teslimat için başarısız durumunda kalırsa → onu otomatik olarak devre dışı bırakır ve çalışma alanı sahibine e-posta göndeririz. Sunucunuzu düzelttikten sonra kontrol panelinden yeniden etkinleştirin.

Teslimat günlüğü

Kontrol panelinde herhangi bir webhook'u açarak son 500 teslimatı, her biri için durum kodu, yanıt süresi ve istek/yanıt gövdesiyle birlikte görün. Başarısız teslimatlar bu görünümden manuel olarak yeniden oynatılabilir.

Yerel test

Webhook'ları localhost'a iletmek için Elido CLI'yi kullanın:

npx @elido/cli webhooks forward --url http://localhost:3000/webhooks

CLI, siz Ctrl-C yapana kadar süren geçici bir uç nokta kaydeder, teslimatları makinenize tünelle iletir ve her olay için istek gövdesini yazdırır.

Sınırlar

• Çalışma alanı başına 20 uç nokta (Pro), 100 (Business).
• 10 KB maksimum imzalı yük boyutu. Daha büyük yükler bölünür — data, bir truncated: true bayrağı ve tam gövdeyi almak için bir URL içerir.
• Uç nokta başına sürekli saniyede 50 olay. Patlamalar kuyruğa alınır.

Sorun giderme

Uç nokta, teslimat günlüğünde 401 bildiriyor. Uç noktanız imzaları yanlış gizli anahtarla doğruluyor. Webhook'lar → Uç nokta → Ayarlar bölümündeki gizli anahtarı sunucunuzun sakladığıyla karşılaştırın.

Bazı olaylar iki kez geliyor. Ya yavaş bir yanıttan sonra yeniden denedik ya da uç noktanız yanıt vermeden zaman aşımına uğradı. Teklik için olay id'sini kullanın.

link.clicked.aggregated sayıları analiz kontrol panosuyla eşleşmiyor. Kontrol paneli gerçek zamanlıdır (tıklamadan 30 saniye içinde); webhook 60 saniyelik pencerelidir. Ayrıca, kontrol panelinden filtrelenen botlar bot filtresi penceresi kapanana kadar ham toplamlara dahil edildiği için küçük (~%1) bir tutarsızlık da vardır.