Skip to main content
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?

PollingWebhook
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.
15 saniye içinde HTTP 2xx döner — Payven delivery timeout’u 15 saniyedir; performans için handler’ınızı 5 saniyenin altında tamamlamayı hedefleyin, 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.completed
X-Payven-Event-Id: evt_8e3f5c129a7b4c8dbc4e2c963f66afa6
X-Payven-Delivery-Id: 9f1c8e76-2a3b-4f12-9c8d-12cb24a8a8a8
X-Payven-Signature: sha256=4f1d8c92ab7e3...
X-Payven-Timestamp: 1714742400

{
  "id": "evt_8e3f5c129a7b4c8dbc4e2c963f66afa6",
  "type": "payment.completed",
  "created_at": "2026-05-03T12:34:56.789+00:00",
  "data": { ... }
}
HeaderAçıklama
X-Payven-EventOlay tipi (örn. payment.completed).
X-Payven-Event-IdOlay kimliği — aynı olay birden fazla teslim edilse bile aynı kalır. Idempotent handler’ınızda bu değeri kullanın.
X-Payven-Delivery-IdTeslim kimliği — her teslim denemesinde farklıdır. Debug ve teslim kaydı eşleştirmesi için kullanılır.
X-Payven-SignatureRequest body’nin HMAC-SHA256 imzası — sha256=<hex> formatında.
X-Payven-Timestampİmzalanan Unix zaman damgası (saniye). Replay saldırılarına karşı 5 dakika tolerans dışındaki istekleri reddedin.

​
İmza doğrulama (kısa)

Request body 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
Tüm bekleme süreleri ±%20 jitter ile uygulanır. 6. denemeden sonra hâlâ başarılı olunmamışsa teslim “kalıcı başarısız” olarak işaretlenir; konsoldan manuel olarak yeniden tetiklenebilir. 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/webhook-subscriptions \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://example.com/webhooks/payven",
    "events": ["payment.completed", "payment.failed", "refund.completed"]
  }'
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,
  • Response body’sini,
  • 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.