Webhook'lar Plus

İlanınız satıldığında veya süresi dolduğunda kendi sunucunuza anlık bildirim alın.

Plus Paketi Gerektirir

Bu sayfadaki endpoint'ler yalnızca Plus (ve üstü: Kurumsal) paketinde çalışır. Diğer paketlerle istek yapıldığında 403 PLAN_UPGRADE_REQUIRED hatası döner. Tüm istekler Authorization: Bearer YOUR_API_KEY başlığı ile gönderilir ve işlemler API anahtarının sahibi olan kullanıcı hesabı üzerinde yapılır.

Nasıl Çalışır?

Kendi tarafınızda POST isteği kabul eden bir endpoint hazırlarsınız.
PUT /api/v1/plus/webhook ile bu adresi ve dinlemek istediğiniz olayları kaydedersiniz.
Olay gerçekleştiğinde KartFiyat, adresinize JSON gövdeli bir POST isteği gönderir.
2xx dönmezseniz gönderim en fazla 3 kez denenir; her deneme loglanır.

Gönderim zaman aşımı 5 saniyedir. Uzun süren işleri isteğe hemen 2xx dönüp arka planda yapın.

Olaylar

Olay	Ayar	Ne zaman tetiklenir
sale	on_sale	Bir ilanınız satıldığında (sipariş kalemi başına bir bildirim)
expire	on_expire	Bir ilanınızın yayın süresi dolduğunda

Gönderilen Gövde

Her istek aynı zarf yapısını kullanır: event, sent_at ve olaya özel data.

// event: sale
{
  "event": "sale",
  "sent_at": "2026-07-27T14:05:02+03:00",
  "data": {
    "order_id": 8891,
    "listing_id": 5044,
    "item_name": "Charizard VMAX",
    "quantity": 1,
    "unit_price": 12500.00,
    "seller_payout": 11875.00,
    "sold_at": "2026-07-27T14:05:02+03:00"
  }
}

// event: expire
{
  "event": "expire",
  "sent_at": "2026-07-27T03:00:11+03:00",
  "data": {
    "listing_id": 5044,
    "title": "Charizard VMAX PSA 10",
    "expired_at": "2026-07-27T03:00:11+03:00"
  }
}

İmza Doğrulama

Her istek X-Kartfiyat-Signature başlığı ile gönderilir. Bu değer, ham JSON gövdesinin webhook secret'ınız ile üretilmiş HMAC-SHA256 özetidir. Gövdeyi işlemeden önce imzayı doğrulayın.

// PHP
$expected = hash_hmac('sha256', file_get_contents('php://input'), $secret);
if (! hash_equals($expected, $_SERVER['HTTP_X_KARTFIYAT_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

// Node.js
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
if (expected !== req.headers['x-kartfiyat-signature']) return res.sendStatus(401);

GET /api/v1/plus/webhook

Mevcut webhook yapılandırmanızı döner. Tanımlı değilse data alanı null olur.

Örnek Yanıt

{
  "success": true,
  "data": {
    "url": "https://siteniz.com/webhooks/kartfiyat",
    "on_sale": true,
    "on_expire": true,
    "is_active": true,
    "secret": "Xk9…48 karakterlik imza anahtarı"
  },
  "note": "Webhook istekleri POST yöntemiyle gönderilir…"
}

PUT /api/v1/plus/webhook

Webhook yapılandırmasını oluşturur veya günceller. secret ilk kayıtta otomatik üretilir ve değişmez.

Gövde Parametreleri

Parametre	Tip	Zorunlu	Açıklama
url	url	Evet	POST isteğini karşılayacak adres (max: 500)
on_sale	boolean	Hayır	Satış bildirimi (varsayılan: false)
on_expire	boolean	Hayır	Süre dolumu bildirimi (varsayılan: false)
is_active	boolean	Hayır	Webhook'u geçici olarak durdurmak için `false` (varsayılan: true)

Örnek İstek

curl -X PUT "https://kartfiyat.com/api/v1/plus/webhook" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://siteniz.com/webhooks/kartfiyat",
    "on_sale": true,
    "on_expire": true,
    "is_active": true
  }'

GET /api/v1/plus/webhook/logs

Gönderim loglarını sayfalı listeler (en yeni önce). per_page varsayılan 20, max 100.

Örnek Yanıt

{
  "success": true,
  "data": [
    {
      "id": 412,
      "event": "sale",
      "attempt": 1,
      "status_code": 200,
      "success": true,
      "error": null,
      "response_excerpt": "OK",
      "created_at": "2026-07-27T14:05:03+03:00"
    }
  ],
  "pagination": { "current_page": 1, "per_page": 20, "total": 96, "last_page": 5, "has_more": true }
}

Başarısız denemelerde status_code hedef sunucunun döndüğü kod, error ise bağlantı/zaman aşımı mesajıdır. Aynı olay için birden fazla attempt kaydı görebilirsiniz.