Webhook'lar

Webhook, Poyra’nın sunucunuza “bir şey oldu” deme yoludur — banka dönüşü sizin sunucunuza değil Poyra’ya geldiği için ödemenin sonucunu size webhook anlatır.

Uç nokta kaydı

curl -X POST https://api.ornek.com/v1/webhook-endpoints \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://uygulamaniz.com/hooks/poyra",
    "eventTypes": ["payment.succeeded", "payment.failed", "refund.succeeded"]
  }'

İmza sırrı (whsec_…) yalnız bu yanıtta ve sır döndürme yanıtında düz görünür; sonrasında bir daha okunamaz. Sır döndürme eskisini anında geçersiz kılar.

Yalnız katalogdaki olay adlarına abone olunabilir; yazım hatası kabul edilmez — sessizce yanlış yazılmış bir abonelik hiç teslimat üretmez ve bunu ancak beklediğiniz çağrı gelmediğinde fark ederdiniz.

Olay kataloğu (16 olay)

Grup	Olaylar
Ödeme	`payment.succeeded` · `payment.failed` · `payment.cancelled` · `refund.succeeded` · `refund.failed`
Abonelik	`subscription.invoice.paid` · `subscription.invoice.failed` · `subscription.card_update_required` · `subscription.unpaid` · `subscription.cancelled`
İtiraz	`dispute.opened` · `dispute.evidence_due_soon` · `dispute.evidence_submitted` · `dispute.won` · `dispute.lost` · `dispute.expired`

Ödeme olayları düz yük taşır (payment_id, amount_minor, currency, hata varsa error); abonelik ve itiraz olayları ortak alanlar + data sarmalayıcısıyla gelir — tek ayrıştırıcı yazarsınız.

Bir teslimat neye benzer

POST /hooks/poyra HTTP/1.1
Content-Type: application/json
Poyra-Event: payment.succeeded
Poyra-Delivery-Id: 7c1f9d2c-…
Poyra-Signature: t=1786371153,v1=8b1c…e40

{ "payment_id": "pay_3f9a…", "amount_minor": 14990, "currency": "TRY", … }

Başlık	Anlamı
`Poyra-Event`	Olay adı
`Poyra-Delivery-Id`	Teslimat kimliği — tekilleştirme anahtarınız
`Poyra-Signature`	`t=<unix saniye>,v1=<hex HMAC-SHA256>`

İmzayı doğrulama

İmzalanan değer "{t}.{ham gövde}" dizesidir; sırrınızla HMAC-SHA256 alınır ve küçük harf hex yazılır. Doğrulamayı ham gövde üzerinde, JSON ayrıştırmadan önce yapın — yeniden serileştirme boşlukları değiştirir ve imza asla tutmaz.

using System.Security.Cryptography;
using System.Text;

static bool Verify(string rawBody, string header, string secret)
{
    var parts = header.Split(',')
        .Select(p => p.Split('=', 2))
        .ToDictionary(p => p[0], p => p[1]);

    if (!long.TryParse(parts.GetValueOrDefault("t"), out var t)) return false;
    // Yeniden oynatmaya karşı pencere — önerilen 5 dakika.
    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;

    var payload = Encoding.UTF8.GetBytes($"{t}.{rawBody}");
    var key = Encoding.UTF8.GetBytes(secret);
    var expected = Convert.ToHexStringLower(HMACSHA256.HashData(key, payload));

    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(parts.GetValueOrDefault("v1") ?? ""));
}

import crypto from "node:crypto";

export function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // önerilen pencere

  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > 300:  # önerilen pencere
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Zaman penceresi (örneklerde 300 saniye) sizin tarafınızda uygulanan bir öneridir; protokol sunucu tarafında bir pencere zorlamaz. İmza aracını kaldırmadan pencereyi ihtiyacınıza göre ayarlayabilirsiniz.

Teslimat garantisi ve yeniden deneme

Başarı ölçütü 2xx’tir; başka her yanıt başarısızlıktır.
Başarısız teslimat üstel aralıklarla yeniden denenir: 1 dk → 5 dk → 30 dk → 2 sa → 6 sa → 24 sa. İlk deneme + 6 tekrar = 7 hak, toplam ~32,5 saat.
Hak bitince kayıt “tükenmiş” olarak kuyrukta kalır; panelden ya da POST /v1/webhook-deliveries/{id}/replay ile elle yeniden gönderilir. Yeniden gönderim eski kaydı değiştirmez, ona bağlı yeni kayıt açar — “kaç kez denendi” sorusu denetimde izlenebilir kalır.
Teslim en az bir keztir: aynı olay birden çok kez gelebilir. İşleyiciniz idempotent olmalı; Poyra-Delivery-Id tekilleştirme anahtarınızdır.
Normal akışta teslim saniyeler içindedir: olay, ödeme sonucunu yazan transaction’da kuyruğa girer ve kuyruk anında dürtülür; dakikalık süpürücü güvencedir.

Teslimat geçmişi GET /v1/webhook-deliveries ile (durum ve uç filtreli) ya da panelin Webhook’lar sayfasından izlenir.

Başlangıç

Ödeme akışları

Ödeme muhasebesi

Operasyon

Panel

Entegrasyon

Kendi sunucunda

Uç nokta kaydı

Olay kataloğu (16 olay)

Bir teslimat neye benzer

İmzayı doğrulama

Teslimat garantisi ve yeniden deneme

​Uç nokta kaydı

​Olay kataloğu (16 olay)

​Bir teslimat neye benzer

​İmzayı doğrulama

​Teslimat garantisi ve yeniden deneme

Uç nokta kaydı

Olay kataloğu (16 olay)

Bir teslimat neye benzer

İmzayı doğrulama

Teslimat garantisi ve yeniden deneme