Webhook'lar

Webhook, bir şey olduğunda Mekante'nin senin sunucuna yaptığı POST isteğidir. Böylece sürekli sorgulamak zorunda kalmadan üyelik, puan ve ödül hareketlerini kendi sisteminde (muhasebe, CRM, SMS…) yakalayabilirsin.

Uç nokta ekleme

Webhook adreslerini yalnızca işletmenin sahibi ekler: panelde Geliştiriciler sayfasında Yeni webhook'a bas, adresi gir, hangi olayları almak istediğini seç ve Adres ekle'ye bas.

Adres herkese açık bir https adresi olmalıdır. Yerel ağ, localhost ve özel IP aralıkları (10.x, 192.168.x, 172.16–31.x…) hem eklerken hem göndermede reddedilir.
Adreste kullanıcı adı ve parola olmamalıdır.
Uç nokta oluşturulurken bir imza anahtarı (whsec_…) üretilir ve yalnızca o anda bir kez gösterilir. Gelen isteği doğrulamak için gerekir (İmza doğrulama). Kaybedersen uç noktayı (Sil) silip yenisini ekle.
Uç noktanın satırındaki menüden Test gönder'i seçersen uç noktana bir ping olayı gider.

Olaylar

Olay	Ne zaman gönderilir
`member.joined`	Bir müşteri işletmeye üye olduğunda
`points.earned`	Puan yazıldığında (`POST /earn`)
`reward.redeemed`	Ödül düşüldüğünde (`POST /redeem`)
`entry.voided`	Bir giriş geri alındığında (`POST /ledger/:id/void`)
`ping`	Yalnızca Test gönder ile. Hangi olaylara abone olduğundan bağımsız, sadece o uç noktaya gider

Her uç nokta yalnızca abone olduğu olayları alır. Olaylar işlem kaydedildikten sonra gönderilir; webhook göndermede bir sorun olsa bile puan yazma işlemi etkilenmez.

İstek biçimi

POST /hooks HTTP/1.1
Content-Type: application/json
User-Agent: Mekante-Webhooks/1
X-Mekante-Event: points.earned
X-Mekante-Signature: t=1792749428,v1=794b3947df267c3354af75b5d8931538c765d768e5ca83983dcd52f7c6f93270

Gövde her olayda aynı zarfı kullanır:

Alan	Açıklama
`id`	Bu gönderimin kimliği. Yeniden denemelerde değişmez
`event`	Olay adı
`createdAt`	Olayın oluştuğu an (ISO 8601, UTC)
`data`	Olaya özel veri (aşağıda)

`member.joined`

{
  "id": "564c1467-e98d-434d-8722-9ffe766b1eeb",
  "event": "member.joined",
  "createdAt": "2026-10-23T09:57:08.193Z",
  "data": {
    "joinedVia": "join_code",
    "membershipId": "db997e9d-3e8c-469b-b385-6d29633f7c6e",
    "marketingConsent": false
  }
}

joinedVia müşterinin nasıl katıldığını söyler: join_code (QR ya da kod ile kendisi) ya da till (kasada, kasiyer SMS bağlantısı gönderdi).

`points.earned`

{
  "id": "d537115b-5aeb-47cb-9232-8e3df03070da",
  "event": "points.earned",
  "createdAt": "2026-10-23T09:57:08.257Z",
  "data": {
    "membershipId": "db997e9d-3e8c-469b-b385-6d29633f7c6e",
    "points": 150,
    "stamps": 0,
    "balance": 150,
    "stampBalance": 0,
    "entryIds": ["3f99048a-4226-4482-a341-682fe57225b2"]
  }
}

points bu işlemde yazılan toplam puandır (bonuslar dahil), stamps yazılan toplam damgadır, balance ve stampBalance yeni bakiyelerdir.

`reward.redeemed`

{
  "id": "8b3d35eb-db0c-4a0e-98c8-198e5dddbc8c",
  "event": "reward.redeemed",
  "createdAt": "2026-10-23T09:57:08.336Z",
  "data": {
    "membershipId": "db997e9d-3e8c-469b-b385-6d29633f7c6e",
    "rewardId": "7d5cb889-f95c-4c59-8e7d-a55a92b6113e",
    "code": "WZ86BV",
    "points": -100,
    "stamps": 0,
    "balance": 250,
    "stampBalance": 3
  }
}

`entry.voided`

data alanları: membershipId, entryId (geri alınan kayıt), points ve stamps (geri verilen ya da düşülen puan ve damga), balance ve stampBalance (yeni bakiyeler).

`ping`

{
  "id": "d6cbcbea-9dfc-45fe-8a44-87c5e7f92ed9",
  "event": "ping",
  "createdAt": "2026-10-23T09:57:08.349Z",
  "data": { "hello": "world" }
}

Yanıt vermen gerekenler

Uç noktan isteği aldığını 2xx bir durumla (örneğin 200) bildirmelidir. Başka bir durum, zaman aşımı ya da bağlantı hatası başarısız sayılır.

Hızlı yanıt ver. İstek 5 saniye içinde yanıtlanmazsa zaman aşımına uğrar. Ağır işi kuyruğa at, önce 200 dön.
Yönlendirmeler izlenmez. 301/302 yanıtı başarısızdır; adresi doğrudan son adrese ayarla.

Yeniden deneme

Başarısız bir gönderim şu aralıklarla yeniden denenir:

Deneme	Önceki denemeden sonra
2.	1 dakika
3.	5 dakika
4.	30 dakika
5.	2 saat
6.	12 saat

Altıncı denemeden sonra gönderim başarısız olarak işaretlenir ve vazgeçilir (toplam yaklaşık 14,5 saat).

Aynı olay iki kez gelebilir

Yeniden deneme yüzünden aynı olayı birden fazla alabilirsin. Gövdedeki id her denemede aynıdır: işlediğin id'leri sakla ve tekrar geleni yok say.

Sıra garantisi yoktur. Olayları createdAt'e göre sırala; bakiye için en güvenilir değer her olaydaki balance alanıdır.