Bağlantı ve çalışma alanı olaylarına abone olun: Webhooks

Webhooks, olayları gerçekleştiği anda Elido'dan sunucunuza gönderir; böylece API'yi sorgulamanız gerekmez. Yaygın kullanım alanları: bağlantı meta verilerini bir CRM ile senkronize etmek, dahili bağlantı dizinini güncel tutmak veya bir bağlantı yayınlandığında iş başlatmak.

Webhooks; bağlantılardaki, alan adlarındaki, üyelerdeki ve çalışma alanındaki değişiklikleri kapsar. Tek tek tıklamaları taşımaz. Tıklama verileri için tıklama dışa aktarma veya Mixpanel gibi bir olay entegrasyonu kullanın. Tıklama başına webhook olayları planlanmıştır.

Webhook uç noktası ekleme

1. Dashboard → Webhooks bölümüne gidin.
2. POST göndermemiz gereken URL'yi ve isteğe bağlı bir açıklamayı girin.
3. Uç nokta türünü seçin: Events (olay türlerini siz seçersiniz) veya SIEM (firehose) (çalışma alanındaki her olay).
4. Events uç noktası için istediğiniz olay türlerini işaretleyin. link.* olayları varsayılan olarak işaretlidir.
5. Add endpoint düğmesine tıklayın. İmzalama gizli anahtarı formun hemen altında yalnızca bir kez görünür. Şimdi kopyalayın: Elido bunu tekrar göstermez.

URL HTTPS olmalıdır. Düz http://, uç noktayı kaydettiğinizde reddedilir; yerel geliştirme için localhost ve 127.0.0.1 izinli kalmaya devam eder.

Bir uç noktayı listeden duraklatabilir ve sürdürebilirsiniz. Duraklatılmış bir uç noktaya yeni teslimat yapılmaz ve onun için hâlâ kuyruğa alınmış her şey siz sürdürene kadar bekler.

Webhook'ları kim yönetebilir

Çalışma alanındaki herkes uç noktaları ve teslimat günlüğünü görüntüleyebilir. Oluşturma, düzenleme, duraklatma, silme, gizli anahtarı döndürme ve bir teslimatı yeniden deneme işlemleri, yerleşik Admin ve Owner rollerinde bulunan workspace.edit iznini gerektirir. Bir API anahtarı, rolünde bu izin varsa API'nin aynı webhook uç noktalarını çağırabilir.

Uç nokta türleri

• Events (event): yalnızca abone olduğunuz olay türlerini alır. İmzalıdır.
• SIEM (siem): audit.event dahil olmak üzere çalışma alanı için yayınlanan her olayı alır; her denetim günlüğü girdisi için bir tane gönderilir. İmzalıdır. Günlük işlem hatları ve güvenlik araçları için tasarlanmıştır.
• Discord, Telegram ve Sentry: aynı teslimat sistemini yeniden kullanan, ancak sağlayıcının kendi mesaj biçimini gönderen sohbet ve uyarı kanallarıdır. Sağlayıcının URL'si veya belirteci üzerinden kimlik doğruladıkları için imza başlığı taşımazlar. Bkz. Discord, Telegram ve Sentry.

İmzalar ve gizli anahtarlarla ilgili aşağıdaki her şey yalnızca Events ve SIEM uç noktaları için geçerlidir.

Olay kataloğu

Adlar <resource>.<action> biçimini izler. Panel formu en yaygın olanları sunar; API üzerinden bir Events uç noktasını bu listedeki herhangi bir türe abone edebilir, SIEM uç noktası ise hepsini alır.

Dashboard seçicisinde:

• link.created: toplu oluşturulanlar da dahil olmak üzere bir kısa bağlantı oluşturuldu.
• link.updated: bir bağlantı değişti (hedef, başlık, etiketler, süre sonu ve benzeri), geri yüklendi, durumu değişti veya moderasyon tarafından güvenlik durumu değiştirildi.
• link.deleted: bir bağlantı mantıksal olarak silindi.
• workspace.updated: çalışma alanı ayarları değişti.
• workspace.created: bir çalışma alanı oluşturulduğunda yayınlanır. Oluşturulmadan önce çalışma alanında hiçbir uç nokta bulunamayacağı için normalde bunu almazsınız.
• member.invited: doğrudan ekleme, davetin kabul edilmesi veya SCIM sağlama yoluyla biri çalışma alanına katıldı.
• member.removed: bir üye elle veya SCIM aracılığıyla kaldırıldı.
• audit.event: her denetim günlüğü girdisi için bir olay.

API üzerinden veya bir SIEM uç noktası aracılığıyla kullanılabilir:

• link.expired: bir bağlantının süresi doldu.
• link.cap_reached: bir bağlantı tıklama sınırına ulaştı. data, cap ve clicks alanlarını içerir.
• link.broken: Elido'nun bağlantı durumu denetimi hedefin başarısız olduğunu buldu. data, status_code, error_message ve first_seen_at alanlarını içerir.
• Şifrelenmiş bağlantılar için link.encrypted_created ve link.encryption_rotated.
• domain.verified: özel bir alan adı DNS denetimini geçti.
• domain.ssl_failed: özel bir alan adının DNS kayıtları eklenmesinden 24 saat sonra hâlâ bulunamadı. Adına rağmen bu, sertifika yenilemeyle değil DNS doğrulamasıyla ilgilidir.
• member.role_changed: bir üyenin rolü değişti. data, old_role, new_role ve changed_by_user_id alanlarını içerir.
• invitation.created ve invitation.accepted.
• Faturalandırma olayları: subscription.* (örneğin subscription.activated, subscription.renewed, subscription.canceled) ve usage.threshold_80, usage.threshold_100.

Planlandı, bugün gönderilmiyor: link.clicked.aggregated (pencere başına bağlantı tıklama sayıları), tıklama başına olaylar, conversion.recorded, domain.tls_renewed, qr.generated ve ayrı bir abuse.flagged olayı. Bir bağlantıyla ilgili moderasyon kararı şu anda yeni abuse_status ile birlikte link.updated olarak gelir.

Yük biçimi

İmzalı her teslimat, Content-Type: application/json, User-Agent: Elido-Webhooks/1.0 ve aşağıdaki kapsayıcıyla birlikte bir POST isteğidir:

{
  "type": "link.created",
  "workspace_id": 4123,
  "timestamp": "2026-09-22T09:42:11Z",
  "data": {
    "id": 891234,
    "workspace_id": 4123,
    "domain_id": 12,
    "slug": "spring-2026",
    "destination_url": "https://acme.com/spring-sale",
    "title": "Spring sale",
    "tags": ["email"],
    "status": "active",
    "expires_at": null,
    "created_by_user_id": 5821,
    "created_at": "2026-09-22T09:42:11Z"
  }
}

• type, olay türüdür. Ayrıca X-Webhook-Event başlığında da bulunur.
• timestamp, olayın UTC cinsinden gerçekleştiği zamandır.
• data, olaya göre değişir. link.* olaylarında tam bağlantı nesnesidir (yukarıdaki örnek kısaltılmıştır). Diğer olaylarda katalogda listelenen kimlikleri ve alanları içeren küçük bir nesnedir.
• Gizli anahtarlar Elido'dan dışarı çıkmaz: bağlantının parola hash'i veya davet belirteci gibi alanlar teslimattan önce data içinden kaldırılır.

Gövde içinde henüz olay id alanı yoktur; olay başına bir kimlik planlanmıştır. İdempotency için aşağıda açıklanan X-Webhook-Delivery başlığını kullanın.

Başlıklar ve imzalar

Events veya SIEM uç noktasına yapılan her teslimat şunları taşır:

Başlık	Değer
X-Elido-Signature	v1= ve ardından hex HMAC-SHA256 imzası
X-Webhook-Signature	Daha eski entegrasyonlar için korunan, X-Elido-Signature ile aynı değer
X-Webhook-Timestamp	Bu isteğin imzalandığı saniye cinsinden Unix zamanı
X-Webhook-Event	Olay türü, örneğin link.created
X-Webhook-Delivery	Teslimat kimliği. Aynı teslimatın yeniden denemelerinde aynı kalır
X-Elido-Signature-Previous	Yalnızca gizli anahtar döndürme sırasında: eski anahtarla oluşturulan aynı imza

İmza şu şekilde hesaplanır:

v1=hex( HMAC-SHA256( secret, "{X-Webhook-Timestamp}.{raw request body}" ) )

Anahtar, whsec_ ön eki dahil olmak üzere gizli anahtarınızın tamamıdır ve olduğu gibi kullanılır. Yeniden serileştirilmiş bir JSON nesnesini değil, aldığınız ham baytları imzalayın ve sabit zamanda karşılaştırın. Kısa bir Node örneği (Express):

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.ELIDO_WEBHOOK_SECRET; // full whsec_... value

function same(a, b = "") {
  const x = Buffer.from(a);
  const y = Buffer.from(b);
  return x.length === y.length && timingSafeEqual(x, y);
}

const app = express();
app.post(
  "/webhooks/elido",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ts = req.get("X-Webhook-Timestamp") ?? "";
    if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
      return res.status(400).send("stale timestamp");
    }
    const expected =
      "v1=" +
      createHmac("sha256", SECRET)
        .update(`${ts}.`)
        .update(req.body)
        .digest("hex");
    const ok = [
      req.get("X-Elido-Signature"),
      req.get("X-Elido-Signature-Previous"),
    ].some((sig) => same(expected, sig));
    if (!ok) return res.status(401).send("bad signature");

    const event = JSON.parse(req.body.toString("utf8"));
    // queue event for processing, then answer quickly
    res.sendStatus(200);
  },
);

Python ve Go sürümleri, bir test vektörü ve yaygın hatalar için webhook imzalarını doğrulama sayfasına bakın.

İmzalama gizli anahtarını döndürme

Uç noktayı Dashboard → Webhooks bölümünde açın ve Rotate secret düğmesine tıklayın. Yeni whsec_ gizli anahtarı bir kez gösterilir ve Elido bundan sonra onunla imzalar.

Eski anahtar 7 günlük bir geçiş süresi boyunca geçerli kalır. Bu süre içinde her teslimat iki imza taşır: yeni anahtarla X-Elido-Signature ve eski anahtarla X-Elido-Signature-Previous; böylece henüz geçiş yapmamış bir alıcı doğrulamaya devam eder. Yeni gizli anahtarı kullanıma alırken iki başlıktan herhangi birini kabul edin.

22 Eylül 2026'dan önce oluşturulan uç noktalar bir istisnadır: bunların ilk döndürülmesi X-Elido-Signature-Previous oluşturmaz; bu nedenle orijinal gizli anahtar hemen çalışmayı bırakır. İlk döndürmeden hemen sonra yeni gizli anahtarı dağıtın. O tarihten beri oluşturulan uç noktalar ilk döndürmeden itibaren çift imzalı gönderim yapar. İkinci döndürmeden itibaren 7 günlük çakışma uygulanır.

Yeniden denemeler

Bir teslimat, 2xx olmayan bir yanıt, ağ hatası veya 10 saniye içinde hiç yanıt alınmaması durumunda başarısız olur. Her teslimat toplam 3 deneme alır:

1. İlk deneme, olaydan birkaç saniye sonra.
2. İlk başarısızlıktan yaklaşık 5 dakika sonra bir yeniden deneme.
3. İkinci başarısızlıktan yaklaşık 15 dakika sonra son bir yeniden deneme.

Üçüncü deneme de başarısız olursa teslimat failed olarak işaretlenir ve otomatik olarak tekrar denenmez. Uç nokta etkin kalır ve yeni olaylar gönderilmeye devam eder. Uç noktanız aynı teslimatı birden fazla kez görebilir (örneğin bir isteği işlediği halde 10 saniyelik zaman aşımından sonra yanıt verdiğinde); bu nedenle X-Webhook-Delivery ile yinelemeleri ayıklayın.

Teslimat günlüğü

En son 100 teslimatı görmek için Dashboard → Webhooks bölümünde bir uç noktayı açın. Her biri için olay türünü, durumu (pending, delivered veya failed), sunucunuzun döndürdüğü HTTP durumunu, yanıt süresini, 3 denemeden kaçının kullanıldığını, oluşturulma ve tamamlanma zamanlarını, bekleyenler için sonraki yeniden deneme zamanını, son hatayı ve gönderilen tam yükü görürsünüz.

Teslim edilmiş veya başarısız olmuş her teslimatta bir Retry düğmesi bulunur. Aynı teslimatı yeniden kuyruğa alır (aynı X-Webhook-Delivery kimliğiyle ve yeni imzayla) ve 3 denemelik yeni bir bütçe verir. API üzerinden GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries, limit (en fazla 100) ve offset ile eski teslimatları sayfalar; POST .../deliveries/{delivery_id}/retry ise düğmeyle aynı işlemi yapar. Bir teslimatı kendiniz yeniden oynatamıyorsanız Elido destek ekibi bunu sizin için yapabilir.

Sunucunuzun yanıt gövdesinin günlüğe kaydedilmesi planlanıyor.

Yerel test

Webhook'ları localhost adresine ileten bir CLI komutu (npx @elido/cli webhooks forward) planlanıyor. O zamana kadar ngrok veya Cloudflare Tunnel gibi bir tünel aracılığıyla yerel sunucunuzu dışarı açın, tünelin HTTPS URL'sini uç nokta olarak ekleyin ve işiniz bittiğinde kaldırın.

Sınırlar

• Uç noktanızın yanıt vermesi için 10 saniye.
• Olay başına 3 teslimat denemesi ve manuel yeniden denemeler.
• Teslimat günlüğü API'si sayfa başına en fazla 100 teslimat döndürür.

Sorun giderme

İmza hiçbir zaman eşleşmiyor. Yaygın nedenler: çerçeveniz JSON'u siz hash'lemeden önce ayrıştırıp yeniden serileştirmiştir (ham gövdeyi hash'leyin), anahtardaki whsec_ ön ekini kaldırmışsınızdır veya gövdenin timestamp değerini X-Webhook-Timestamp başlığı yerine kullanarak imzalıyorsunuzdur. İmza doğrulama yazısında kodunuzu karşılaştırabileceğiniz bir test vektörü bulunur.

Döndürmeden sonra imza eşleşmemeye başladı. Sunucunuzda hâlâ eski gizli anahtar var. Yenisiyle dağıtım yapın. 22 Eylül 2026'dan önce oluşturulan bir uç noktanın ilk döndürülmesinde geri dönüş için X-Elido-Signature-Previous bulunmaz.

Bazı olaylar iki kez geliyor. Elido, uç noktanız bir hatayla yanıt verdiği veya 10 saniyeden uzun sürdüğü için yeniden denedi. X-Webhook-Delivery ile yinelemeleri ayıklayın ve yavaş işleri yapmadan önce 2xx ile yanıt verin.

Bir olay türü hiç gelmiyor. Uç noktanın bu türe abone olduğunu ve duraklatılmadığını, ayrıca türün yukarıdaki katalogda bulunduğunu kontrol edin. Planlandı olarak işaretlenen türler henüz gönderilmez.