Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt

Use this file to discover all available pages before exploring further.

Webhook’lar, sunucunuza HTTP POST isteği göndererek ödeme, iade, mutabakat gibi olayları gerçek zamanlı bildirir. Polling yerine event-driven çalışmanın yoludur.
Bu sayfa genel webhook prensiplerini açıklar. Sanal POS özelinde olay listesi ve örnek payload’lar için: Sanal POS Webhook Olayları.

​
Neden webhook?

Polling (sorgulama)Webhook
Sürekli GET istekleriyle durum sorgulanırOlay gerçekleşince Payven sizin endpoint’inize bildirir
Gecikme: sorgulama aralığı kadarGecikme: saniyenin altı
Rate limit kotanızı tüketirLimitten muaf
Sunucu kaynağını boşa kullanırSadece olay olduğunda çalışır

​
Akış

​
Endpoint kuralları

Webhook endpoint’iniz aşağıdaki kurallara uymalıdır:
HTTPS zorunlu — HTTP URL’leri reddedilir.
Public erişilebilir — özel ağ veya VPN arkasında olamaz.
5 saniye içinde HTTP 2xx döner — uzun süren işler için iş kuyruğa atılmalıdır.
Idempotent çalışır — aynı olay birden fazla kez gelebilir.
İmzayı doğrular — sahte istekleri reddeder.

​
Genel istek formatı

POST /webhooks/payven HTTP/1.1
Host: example.com
Content-Type: application/json
X-Payven-Event: payment.succeeded
X-Payven-Delivery: 9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8
X-Payven-Signature: sha256=4f1d8c92ab7e3...
X-Payven-Timestamp: 1714742400

{
  "id": "evt_8e3f5c12",
  "type": "payment.succeeded",
  "createdAt": "2026-05-03T12:34:56Z",
  "data": { ... }
}
HeaderAçıklama
X-Payven-EventOlay tipi (örn. payment.succeeded)
X-Payven-DeliveryTeslim kimliği — debug için kullanılır
X-Payven-SignatureHMAC-SHA256 imza
X-Payven-Timestampİmzalanan Unix zaman damgası

​
İmza doğrulama (kısa)

İstek gövdesi ile timestamp’i subscription.secret ile HMAC-SHA256 hashlenir. Detay ve kod örnekleri: İmza Doğrulama. 
hmac = HMAC_SHA256(secret, timestamp + "." + body)
signature_header = "sha256=" + hex(hmac)

​
Yeniden deneme

İlk denemede 2xx dönmezse Payven otomatik olarak yeniden dener:
DenemeBekleme süresi
1Hemen
21 dakika
35 dakika
430 dakika
52 saat
624 saat
Detay: Yeniden Deneme Politikası.

​
Abone olmak

Webhook abonelikleri her ürün için ayrı tanımlanır. Sanal POS örneği: 
curl -X POST https://vpos.payven.com.tr/api/v1/webhooks \
  -H "X-API-Key: pvk-prod-XXXX" \
  -H "X-API-Secret: YOUR_SECRET" \
  -H "X-Merchant-Id: 3fa85f64-..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/payven",
    "events": ["payment.succeeded", "payment.failed", "refund.succeeded"]
  }'
Yanıttaki secret değerini saklayın — imza doğrulamasında kullanacaksınız.

​
Test ve debug

Konsol → Webhook Teslim Kayıtları ekranından her teslim denemesinin:
  • HTTP yanıt kodunu,
  • Yanıt gövdesini,
  • Süresini,
  • Yeniden deneme sayısını,
  • Tam request/response payload’unu
görebilirsiniz. Lokal geliştirmede ngrok veya Cloudflare Tunnel gibi araçlarla local endpoint’inizi internete açabilirsiniz.