Webhook'lar

Cüzdanın asenkron sonuçları webhook ile bildirilir. Para hareketlerinin sonucunu polling ile değil webhook ile öğrenin; GET uçları teyit içindir.

Olay kataloğu

Bakiye yükleme

Transfer

Para çekme

Ödeme ve iade

Sadakat

Fatura ve fatura ödeme

Operasyon

Zarf

Her teslimat aynı zarfla gelir; cüzdan olayının kendi alanları data altındadır:

{
  "id": "0b6d3f2e-9a41-4c7e-8d25-6f1a3b9c4e07",
  "type": "wallet.transfer.completed",
  "sourceService": "wallet-service",
  "organizationId": "3c9a1e5b-7d2f-4b8e-a6c4-1f0e9d2b7a35",
  "productCode": "WALLET_SERVICE",
  "environment": "LIVE",
  "eventVersion": 1,
  "schemaVersion": "v1",
  "createdAt": "2026-08-07T12:00:04.512Z",
  "data": {
    "schemaVersion": "wallet.webhook.v1",
    "domain": "WALLET",
    "eventName": "wallet.transfer.completed",
    "operationId": "7a3e9c1d-2b4f-4e8a-9d6c-0f5b8e2a1c93",
    "sourceWalletAccountId": "c2a5e8f1-9d3b-4c7a-8e6f-5b1d2a9c0e47",
    "destinationWalletAccountId": "a4d7b0e3-5f8c-4a1d-9b2e-6c3f8a1d0e59",
    "amount": "10050",
    "currency": "TRY",
    "feeTotal": "250",
    "taxTotal": "125"
  }
}

data içinde:

data içinde bunların yanında olaya özgü alanlar taşınır (operasyon kimliği, tutarlar, durum).

İmza doğrulama

Her teslimat şu header'ları taşır:

v2 imzası ham gövdenin HMAC'idir — gövdeyi parse etmeden doğrularsınız:

signature = HMAC-SHA256( secret, "{eventId}.{timestamp}.{rawBody}" )

Başlıktaki her v2= öğesini bu değerle sabit zamanlı karşılaştırın; herhangi biri eşleşirse imza geçerlidir (secret rotasyonunun 24 saatlik grace penceresinde iki v2= öğesi bulunur).

import { createHmac, timingSafeEqual } from 'node:crypto';
 
export function verifyWalletWebhook(rawBody, headers, secret, toleranceSeconds = 300) {
  const eventId   = headers['x-lunixi-event-id'];
  const timestamp = headers['x-lunixi-signature-timestamp'];
  if (Math.abs(Date.now() - Date.parse(timestamp)) > toleranceSeconds * 1000) return false;
 
  const expected = createHmac('sha256', secret)
    .update(`${eventId}.${timestamp}.${rawBody}`)
    .digest('hex');
 
  return String(headers['x-lunixi-signature'] || '')
    .split(',')
    .map((item) => item.trim())
    .filter((item) => item.startsWith('v2='))
    .some((item) => {
      const received = Buffer.from(item.slice(3), 'hex');
      const wanted = Buffer.from(expected, 'hex');
      return received.length === wanted.length && timingSafeEqual(received, wanted);
    });
}

Teslim garantisi

Cüzdan webhook'ları en az bir kez (at-least-once) teslim edilir:

• Bir operasyonun durumu değiştiğinde (ör. completed, failed, reversed) ilgili olay, durum değişikliğiyle aynı işlemde kaydedilir. Operasyon bir duruma ulaştıysa o durumun olayı da üretilmiştir; altyapı kesintisinde olay kaybolmaz, kesinti bittiğinde gecikmeli olarak teslim edilir.
• Aynı olay birden fazla kez teslim edilebilir. Her tekrar aynı x-lunixi-event-id değerini taşır; bu değer olay başına sabittir ve tekilleştirme anahtarı olarak kullanılmalıdır.
• Olaylar gecikmeli gelebilir. Operasyonun güncel durumunu her zaman GET /wallet/operations/{id} ile teyit edebilirsiniz.

Yeniden deneme

Endpoint'iniz 2xx dönmezse teslimat yeniden denenir. Bekleme süreleri sabit bir cetvele göredir ve her değere ±%20 jitter uygulanır; deneme hakkı tükendiğinde teslimat dead letter olarak işaretlenir (DEAD_LETTER).

Doğru tüketim

1. Hızlı 2xx dönün. İşi kuyruğa alın; webhook isteği içinde uzun iş yapmayın — zaman aşımı yeniden denemeye yol açar.
2. Idempotent olun. Teslimat en az bir kezdir; aynı olay birden fazla kez gelebilir. x-lunixi-event-id'yi saklayın ve aynı kimlikle gelen tekrarı yok sayın.
3. Sıra garantisi yoktur. completed olayı processing'den önce gelebilir. Durumu olayın sırasına değil içeriğine göre yazın; şüphede GET /wallet/operations/{id} ile teyit edin.
4. Bilinmeyen olayı yok sayın. Yeni olay tipleri eklenebilir; tanımadığınız type için 2xx dönüp geçin.
5. 3xx döndürmeyin. Yönlendirme takip edilmez.

Kurulum

Endpoint URL'nizi ve dinleyeceğiniz olayları merchant panelden tanımlarsınız; imza secret'ınız orada üretilir. Endpoint'iniz herkese açık ve HTTPS olmalıdır.

Yaygın hatalar