Webhook Kurulumu

Bu sayfa yönetim tarafını anlatır. Gelen teslimatın sözleşmesi (başlıklar, imza, yeniden deneme) ayrı sayfada: Webhook'lar.

Endpoint'leri hem panelden hem API'den yönetebilirsiniz; ikisi de aynı kontrol düzlemine bağlanır.

Erişim gereksinimleri

Bearer token'ın sahibi (principal) webhooks:manage iznine sahip olmalı.
Organizasyonun webhook entitlement'ı açık olmalı — değilse tüm çağrılar 403 webhook.entitlement.not_enabled döner.

Uçlar

Tümü https://api-gateway.lunixi.com tabanına ve Bearer token'a bağlıdır.

Yöntem	Yol	İş
`POST`	`/api/v1/organizations/{orgId}/webhook-endpoints`	Endpoint oluştur
`GET`	`/api/v1/organizations/{orgId}/webhook-endpoints`	Endpoint'leri listele
`GET`	`/api/v1/organizations/{orgId}/webhook-endpoints/{endpointId}`	Tek endpoint
`PUT`	`/api/v1/organizations/{orgId}/webhook-endpoints/{endpointId}`	Güncelle
`DELETE`	`/api/v1/organizations/{orgId}/webhook-endpoints/{endpointId}`	Devre dışı bırak
`GET`	`/api/v1/organizations/{orgId}/webhook-deliveries`	Teslimat geçmişi
`POST`	`/api/v1/organizations/{orgId}/webhook-deliveries/{deliveryId}/replay`	Teslimatı yeniden oynat

DELETE silmez, devre dışı bırakır. Endpoint ve teslimat geçmişi kayıtta kalır — denetim izini korumak için. Aynı adresi tekrar kullanmak isterseniz yeni bir endpoint oluşturursunuz.

Endpoint'in alanları

Alan	Anlamı
`name`	Panelde göreceğiniz ad (en fazla 160 karakter)
`url`	Teslimatın gideceği adres — genel internetten erişilebilir olmalı
`productCode`	Hangi ürünün olaylarını alacağı (ör. `PAYMENT_GATEWAY`)
`environment`	Ortam ayrımı — `TEST` veya `LIVE`; canlı ve test endpoint'ler karışmaz
`secretRef`	Zorunlu. İmza secret'ının Secret Vault referansı: `vault:<secretId>` — secret'ın kendisi API'de asla dolaşmaz
`eventTypes`	Zorunlu. Abone olunan olay tipleri; joker desteklenir (ör. `["payment.*"]`)
`status`	`ACTIVE` · `FAILED` (art arda hata sonrası otomatik)
`failureCount`	Art arda başarısız deneme sayacı — başarılı teslimatta sıfırlanır
`lastSuccessAt` / `lastFailureAt`	Son başarı / son hata zamanı

Olay abonelikleri endpoint'e bağlıdır ve olay tipi bazındadır; bir endpoint'i yalnız ilgilendiği olaylara abone edersiniz. DELETE davranışı değişmedi: silmez, devre dışı bırakır.

Banka hesabı olayları için endpoint'i productCode: "BANK_CONNECT" ve eventTypes: ["bank_account.*"] ile oluşturun; transfer olaylarını da almak için listeye "bank_transfer.*" ekleyin. → Banka Hesapları › Webhook Olayları

Sigorta olayları için endpoint'i productCode: "INSURANCE_SERVICE" ve eventTypes: ["insurance.*"] ile oluşturun. → Sigorta › Webhook Olayları

Kurulum akışı

Endpoint'inizi hazırlayın

Genel internetten erişilebilen, POST kabul eden bir adres. İlk sürümde tek işi olsun: imzayı doğrulayın, olayı kendi kuyruğunuza yazın, 2xx dönün. İş mantığını senkron çalıştırmayın — teslimat zaman aşımı varsayılan 10 saniye.

İmza secret'ını oluşturun

API secret üretmez ve döndürmez — imza secret'ı Secret Vault'ta yaşar, endpoint ona yalnız secretRef ile bağlanır. İki yol var:

Panel yolu. Panel, endpoint oluştururken whsec_… biçiminde bir secret'ı istemci tarafında üretir, Secret Vault'a yazar ve secretRef'i otomatik ayarlar. Secret yalnız bir kez gösterilir — kendi kasanıza saklayın; kaybederseniz okuyamazsınız, yalnız yenisiyle değiştirebilirsiniz.

API yolu. Secret'ı önce kendiniz üretip vault'a yazarsınız, dönen id'yi endpoint çağrısına verirsiniz:

curl -X POST "https://api-gateway.lunixi.com/api/v1/secrets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "<orgId>",
    "secretKey": "webhook/<orgId>/LIVE/PAYMENT_GATEWAY/<name>",
    "payload": { "signingSecret": "whsec_<sizin ürettiğiniz ≥32 karakter rastgele değer>" }
  }'

Yanıttaki secretId'yi secretRef: "vault:<secretId>" olarak kullanacaksınız. Signing secret en az 16 karakter olmalı — pratikte ≥ 32 karakter rastgele değer üretin.

🚫

Secret sunucu tarafında şifreli kasada tutulur ve teslimat anında çözülür — listeleme çağrılarında asla geri dönmez. Bu nedenle secret'ı oluşturma anında kaydetmeniz gerekir; sonradan görüntülenemez.

Endpoint'i oluşturun

curl -X POST "https://api-gateway.lunixi.com/api/v1/organizations/$ORG_ID/webhook-endpoints" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ödeme olayları — canlı",
    "url": "https://merchant.example.com/webhooks/lunixi",
    "productCode": "PAYMENT_GATEWAY",
    "environment": "LIVE",
    "secretRef": "vault:<secretId>",
    "eventTypes": ["payment.*"]
  }'

environment yalnız TEST veya LIVE alır; secretRef ve eventTypes zorunludur.

Doğrulamayı yazın ve test edin

İmza doğrulama kodunu Webhook'lar sayfasından alın. v2 imzası ham gövdenin HMAC'idir — gövdeyi parse etmeden, {eventId}.{timestamp}.{rawBody} üzerinden doğrularsınız.

Canlıya alın

İlk gerçek olay geldikten sonra teslimat geçmişinden doğrulayın.

Teslimat geçmişi

curl "https://api-gateway.lunixi.com/api/v1/organizations/$ORG_ID/webhook-deliveries?status=DEAD_LETTER" \
  -H "Authorization: Bearer $TOKEN"

Süzgeçler: endpointId · eventType · status

Her teslimat kaydı attemptCount, lastErrorCode, lastError, nextRetryAt ve deliveredAt taşır. Denemeler ayrıca tek tek loglanır — hangi denemede hangi HTTP kodunu döndüğünüz görünür.

Başarısız teslimatı yeniden oynatma

curl -X POST "https://api-gateway.lunixi.com/api/v1/organizations/$ORG_ID/webhook-deliveries/$DELIVERY_ID/replay" \
  -H "Authorization: Bearer $TOKEN"

DEAD_LETTER durumundaki bir teslimat böyle geri alınır. Endpoint'iniz bir süre kapalı kaldıysa, aralıktaki teslimatları listeleyip topluca yeniden oynatabilirsiniz.

Yeniden oynatma aynı x-lunixi-event-id ile gider ve deneme bütçesini sıfırlar — teslimat taze 12 deneme hakkıyla kuyruğa döner. Idempotens anahtarını bu başlığa bağladıysanız, daha önce işlediğiniz bir olayı tekrar işlemezsiniz — beklenen davranış budur.

Secret döndürme

Secret'ı döndürdükten sonra platform, teslimatları 24 saat boyunca eski ve yeni secret'la çift imzalar ("grace penceresi"): x-lunixi-signature başlığında iki v2= öğesi bulunur. Herhangi bir v2= öğesi eşleştiğinde imzayı geçerli sayan bir doğrulayıcı — Webhook'lar sayfasındaki örnek böyledir — hiçbir değişiklik gerektirmez. 24 saat sonra eski secret kullanımdan çıkar.

Sıra basit:

Secret'ı döndürün, yeni değeri kasanıza yazın.
Grace penceresi boyunca teslimatlar iki imzayla gelir — doğrulayıcınız herhangi bir v2= eşleşmesini kabul ediyorsa kesinti olmaz.
24 saat sonra eski secret'la imzalama durur; yapmanız gereken başka bir şey yok.

Endpoint kapandıysa

Art arda başarısızlık eşiği aşılınca (varsayılan 20) endpoint'in durumu FAILED olur ve teslimat almayı durdurur. Sunucunuzu onardıktan sonra panelden yeniden etkinleştirin; bu arada biriken teslimatları yeniden oynatabilirsiniz.

İlgili

Webhook'lar — başlıklar, imza, yeniden deneme, teslimat durumları
Kimlik Doğrulama — Bearer token'ı nasıl aldığınız

Webhook'lar Entegrasyon Rehberi