DEV Community

Cover image for Webhook nedir, gelmezse ne yapmalı?
Hüseyin Bozdemir
Hüseyin Bozdemir

Posted on Originally published at huseyinbozdemir.com

Webhook nedir, gelmezse ne yapmalı?

Bir gün raporda bir ödemenin satırı eksik kaldı. Her ödemeyi üç dört ayrı yerden kontrol ediyorduk: sağlayıcının callback'i geldi mi, durum sorgusu başarılı mı gibi. O ödemede diğer işaretler tamamdı. Yalnızca callback işaretlenmemişti.

Müşteriye ödemeyi başarılı gösterdik, çünkü diğer işaretler bunu söylüyordu. Ama callback'in neden gelmediğini sağlayıcıya sorduk. Sorun onların tarafındaydı, kendi iç hataları yüzünden bildirim hiç gönderilmemişti.

Bizim tarafta hata yoktu. Callback'i dinleyen uç çalışıyordu, kuyruk çalışıyordu. Gelmeyen bir şeyi işleyemezsin.

Kısa cevap: webhook bir ipucudur, ödemenin gerçek durumu değil. Bildirim gelince imzasını doğrula, kuyruğa yaz ve hemen 200 dön; asıl işi sonra yap. Aynı bildirimi iki kez işlememek için sipariş anahtarıyla ayıkla. Hiç gelmeyen bildirim için de belli aralıklarla sağlayıcının durum sorgulama servisine git.

Webhook nedir, ödemede ne işe yarar?

Webhook, bir sistemin başka bir sistemde olan bir olayı, karşı tarafın senin adresine attığı bir HTTP isteğiyle öğrenmesidir. Sen sormazsın, karşı taraf haber verir. Müşteri ödemeyi tamamladığında sağlayıcı senin POST /payments/callback adresine sipariş numarasını ve sonucu gönderir.

Ödeme dünyasında buna çoğu zaman callback denir. Bu yazıda ikisini aynı anlamda kullanıyorum.

Tersi polling'dir: sen belli aralıklarla "bu ödeme ne oldu?" diye sorarsın. Webhook daha hızlıdır ve boşuna sorgu atmazsın. Bedeli de şu: teslim karşı tarafın elindedir. Gönderip göndermediğini, kaç kez gönderdiğini o belirler.

3D Secure'da redirect var, webhook değil

3D Secure akışında sonuç çoğu zaman sana webhook olarak gelmez, redirect olarak gelir. Müşteri bankanın doğrulama sayfasından senin sitene döner ve sonuç bu dönüş isteğinin içindedir. Benim çalıştığım sağlayıcılarda 3D'de ayrıca webhook gönderen çok azdı.

Redirect müşterinin tarayıcısından gelir. Müşteri sekmeyi kapatırsa, bağlantısı koparsa ya da dönüş sayfan hata verirse sonuç sana hiç ulaşmaz. Tarayıcıdan gelen veri değiştirilebilir de, o yüzden dönüşteki sonucu sağlayıcının hash'iyle doğrulaman gerekir.

Sunucudan sunucuya gelen webhook bu iki sorunu taşımaz. Ama kendi sorunları var.

Bildirim neden iki kez gelir ya da hiç gelmez?

Sağlayıcı bildirimi gönderir ve senden 2xx bir cevap bekler. Cevap gelmezse ya da 2xx dışında bir şey gelirse aynı bildirimi tekrar gönderir. Stripe bunu canlı ortamda üç güne kadar sürdürür. Razorpay 24 saat dener, sonra webhook'u kapatır.

Bu düzenin adı at-least-once, yani en az bir kez teslim. Tam bir kez teslim garantisi yoktur. Senin uç noktan isteği işledi ve 200 döndü ama cevap ağda kayboldu. Sağlayıcı bunu başarısız sayar ve aynı bildirimi tekrar gönderir. Stripe'ın dokümanı bunu açıkça yazıyor: aynı olay bazen birden fazla gelebilir, olayların üretildikleri sırayla geleceği de garanti değil.

Bir de hiç gelmeme durumu var. Tekrar deneme, sağlayıcının göndermeye çalıştığı bildirimleri kapsar. Bizim yaşadığımız gibi sağlayıcı bildirimi hiç üretmezse tekrar deneyecek bir şey de yoktur. Senin tarafında hiçbir şey olmaz: ne hata, ne log.

Çift gelen bildirimi canlıda gördüğümü hatırlamıyorum. Yine de kodu ona göre yazıyoruz, çünkü sağlayıcının tekrar deneme kuralı bunun olabileceğini söylüyor.

Önce doğrula, kuyruğa yaz, sonra 200 dön

Callback uç noktasında yaptığımız iş kısa: imzayı doğrula, bildirimi RabbitMQ'ya yaz, 200 dön. Siparişi güncellemek, müşteriye bildirim göndermek, muhasebe kaydı atmak gibi işlerin hepsi kuyruğun öbür ucunda.

Sebebi süre. Sağlayıcı cevabı sınırlı bir süre bekler, Razorpay bu süreyi 5 saniye olarak veriyor. Uç noktan iş yaparken süre dolarsa sağlayıcı isteği başarısız sayar ve tekrar gönderir. Sen ise işi çoktan yapmışsındır. İşi uçta yapmak, tekrarı kendi elinle üretmek demek.

İmza doğrulaması 200'den önce

Callback adresin internete açık. Ona istek atan herkes "bu sipariş ödendi" diyebilir. Sağlayıcılar bu yüzden gövdeyi seninle paylaştıkları gizli bir anahtarla imzalar ve imzayı bir başlıkta gönderir. Sen aynı imzayı hesaplar, gelenle karşılaştırırsın.

public sealed class CallbackSignature(byte[] secret)
{
    public bool IsValid(byte[] body, string? header)
    {
        if (string.IsNullOrEmpty(header))
            return false;

        var expected = Convert.ToHexStringLower(HMACSHA256.HashData(secret, body));

        return CryptographicOperations.FixedTimeEquals(
            Encoding.ASCII.GetBytes(expected),
            Encoding.ASCII.GetBytes(header));
    }
}
Enter fullscreen mode Exit fullscreen mode

İki ayrıntı önemli. İmzayı gövdenin ham baytları üzerinden hesapla. Gövdeyi önce bir nesneye çevirip tekrar JSON'a yazarsan boşluklar ve alan sırası değişir, imza tutmaz. Karşılaştırmayı da == ile değil CryptographicOperations.FixedTimeEquals ile yap. Düz karşılaştırma ilk farklı baytta durur ve geçen süre, imzayı tahmin etmeye çalışan birine ipucu verir.

İmza formülü sağlayıcıya göre değişir. Kimi zaman damgasını da imzaya katar, kimi hex yerine Base64 kullanır. Standard Webhooks spesifikasyonu bunu ortak bir biçime oturtmaya çalışıyor (webhook-id, webhook-timestamp, webhook-signature başlıkları). Ama sonunda senin sağlayıcının dokümanı ne diyorsa o.

Kuyruğa yazılamazsa 500

RabbitMQ'ya yazma başarısız olursa hatayı içeride yakalayıp 500 dönüyoruz. 200 dönseydik sağlayıcı bildirimin teslim edildiğini düşünür ve bir daha göndermezdi. Elimizde de hiçbir yerde kaydı olmayan bir ödeme kalırdı. 500 dönünce tekrar denemeyi sağlayıcı üstleniyor.

app.MapPost("/payments/callback", async (
    HttpRequest request,
    CallbackSignature signature,
    ICallbackQueue queue,
    ILogger<Program> logger,
    CancellationToken ct) =>
{
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer, ct);
    var body = buffer.ToArray();

    if (!signature.IsValid(body, request.Headers["X-Signature"]))
        return Results.Unauthorized();

    var callback = JsonSerializer.Deserialize<PaymentCallback>(body)!;

    try
    {
        await queue.PublishAsync(callback, ct);
    }
    catch (Exception ex)
    {
        logger.LogError(ex, "Callback kuyruğa yazılamadı: {OrderId}", callback.OrderId);
        return Results.StatusCode(StatusCodes.Status500InternalServerError);
    }

    return Results.Ok();
});
Enter fullscreen mode Exit fullscreen mode

Burada bir tuzak var. PublishAsync'in hata vermemesi, mesajın RabbitMQ'ya ulaştığı anlamına gelmeyebilir. Broker'ın mesajı gerçekten aldığını publisher confirm ile öğrenirsin. Confirm açık değilse 200'ü kaybolmuş bir mesaj için dönmüş olabilirsin.

Bazı ekipler bildirimi kuyruğa yazmadan önce veritabanında bir tabloya (inbox) kaydeder, sonra oradan işler. Bu, outbox pattern'in gelen mesajlar için aynası. Bizde bildirim doğrudan kuyruğa gidiyor.

Tekrarı sipariş anahtarıyla ayıklamak

Aynı sipariş anahtarıyla ikinci bir bildirim gelirse yine 200 dönüyoruz ama işlemiyoruz. 200 dönmek önemli. Hata dönersen sağlayıcı aynı bildirimi tekrar tekrar gönderir.

Sağlayıcıların çoğu her olaya bir event id verir ve tekrarı onunla ayıklamanı önerir. Event id, aynı olayın tekrar gönderilmesini yakalar. Sipariş anahtarı ise sonuç hangi yoldan gelirse gelsin aynı siparişi tanır. Aşağıda göreceğin durum sorgusu da sonucun ikinci bir yolu.

Kontrolü "var mı diye bak, yoksa işle" diye yazmak kolay:

if (await db.ProcessedCallbacks.AnyAsync(x => x.OrderId == callback.OrderId, ct))
    return; // aynı anda gelen iki kopya buradan birlikte geçebilir
Enter fullscreen mode Exit fullscreen mode

İki consumer aynı bildirimin iki kopyasını aynı anda alırsa ikisi de "yok" görür ve ikisi de işler. Bu, bakiye yazısındaki check-then-act yarışının aynısı. Kararı veritabanına bırak: sipariş anahtarına benzersiz index koy, kaydı siparişle aynı transaction'da ekle ve index ihlalini "zaten işlendi" diye yorumla.

public sealed class PaymentCallbackConsumer(AppDbContext db)
{
    public async Task HandleAsync(PaymentCallback callback, CancellationToken ct)
    {
        var order = await db.Orders.SingleAsync(o => o.Id == callback.OrderId, ct);
        order.Complete(callback.TransactionId);

        db.ProcessedCallbacks.Add(new ProcessedCallback
        {
            OrderId = callback.OrderId,
            ProcessedAt = DateTimeOffset.UtcNow,
        });

        try
        {
            await db.SaveChangesAsync(ct); // sipariş ve kayıt tek transaction'da
        }
        catch (DbUpdateException ex) when (ex.IsUniqueViolation())
        {
            // Bu sipariş daha önce işlenmiş. Mesajı onayla ve geç.
        }
    }
}
Enter fullscreen mode Exit fullscreen mode
modelBuilder.Entity<ProcessedCallback>()
    .HasIndex(x => x.OrderId)
    .IsUnique();

// SQL Server: 2601 ve 2627. PostgreSQL'de PostgresException { SqlState: "23505" }.
public static bool IsUniqueViolation(this DbUpdateException ex) =>
    ex.InnerException is SqlException { Number: 2601 or 2627 };
Enter fullscreen mode Exit fullscreen mode

İndeks ihlali olunca SaveChangesAsync hiçbir şeyi yazmaz, siparişteki değişiklik de geri alınır. Tekrar gelen bildirim siparişe dokunmadan düşer. Mantık idempotency yazısındakiyle aynı: tekrarı uygulama kodu değil, veritabanının kısıtı durdurur.

Bildirim sırasız gelirse

Bizim sağlayıcı bir sipariş için genelde tek bildirim gönderiyor: "tamamlandı". O yüzden ikinci bildirimi atlamak bizde doğru.

Ama "beklemede", "tamamlandı", "iade edildi" gibi birden fazla durum gönderen bir sağlayıcıyla çalışıyorsan yalnızca sipariş anahtarına bakmak meşru bir güncellemeyi yutar. "Tamamlandı"dan sonra gelen "iade edildi" tekrar sanılır ve atlanır. Üstelik bildirimlerin sırayla geleceği de garanti değil.

O durumda anahtar sipariş artı durum olur. Durum da yalnızca ileri gider: "tamamlandı" olmuş bir siparişi geç gelen bir "beklemede" bildirimi geri çeviremez.

Bildirim hiç gelmezse: 30 dakikada bir durum sorgusu

Gelmeyen bildirimi beklemekle bulamazsın. Bunun için bizde 30 dakikada bir çalışan bir job var. Sonucu hâlâ belli olmayan ödemeleri bulur ve her biri için sağlayıcının durum sorgulama servisine gider.

Neden 30 dakika? 3D Secure bazen uzayabiliyor. Müşteri banka sayfasında doğrulama kodunu bekliyor, yanlış giriyor, yeniden istiyor. Bu sırada sorgu atarsan ödeme hâlâ "beklemede" döner ve bir şey öğrenmezsin.

public sealed class PendingPaymentJob(AppDbContext db, IPaymentProvider provider, ICallbackQueue queue)
{
    public async Task RunAsync(CancellationToken ct)
    {
        var cutoff = DateTimeOffset.UtcNow.AddMinutes(-30);

        var pending = await db.Orders
            .Where(o => o.Status == OrderStatus.AwaitingPayment && o.CreatedAt < cutoff)
            .OrderBy(o => o.CreatedAt)
            .Select(o => o.Id)
            .Take(200)
            .ToListAsync(ct);

        foreach (var orderId in pending)
        {
            var status = await provider.GetPaymentStatusAsync(orderId, ct);

            if (status.IsCompleted)
                await queue.PublishAsync(PaymentCallback.FromStatus(status), ct);
        }
    }
}
Enter fullscreen mode Exit fullscreen mode
RecurringJob.AddOrUpdate<PendingPaymentJob>(
    "bekleyen-odemeler",
    job => job.RunAsync(CancellationToken.None),
    "*/30 * * * *");
Enter fullscreen mode Exit fullscreen mode

Bu kodda job, sorgunun sonucunu siparişe kendisi yazmıyor. Callback'in gittiği kuyruğa yazıyor. Bunu sana öneririm, çünkü böylece sonucu işleyen tek bir yer kalır:

Diyagram: Ödeme sonucu iki yoldan gelir. Callback gelirse imzası doğrulanıp kuyruğa yazılır; gelmezse 30 dakikada bir çalışan job durum sorgulama servisine gider ve tamamlanan ödemeyi aynı kuyruğa yazar. Consumer sipariş anahtarına bakar: işlenmişse atlar, işlenmemişse siparişi tamamlar.

Callback ile sorgu sonucu aynı anda gelirse ne olur? Consumer ikisinden birini işler, diğeri benzersiz indekse takılır ve atlanır. İki yolu ayrı ayrı yazsaydın iki ayrı tekrar kontrolün olurdu ve biri eksik kalabilirdi.

Sorgu "başarısız" ya da "süresi doldu" derse ne yapılacağı ayrı bir karar. Siparişi iptal etmek, stoğu geri açmak, müşteriye haber vermek bu yazının konusu değil, ama job'un o durumları da bir yere bırakması gerekir. Yoksa aynı ödemeyi her 30 dakikada bir yeniden sorgularsın.

Tek işarete güvenmemek

Callback'in gelmediğini fark etmemizi sağlayan şey bir rapordu. Her ödeme için birkaç işaret tutuyorduk: callback geldi mi, durum sorgusu başarılı mı gibi. Hepsi aynı şeyi söylüyorsa sorun yok. Biri eksikse rapor onu gösteriyor.

Kendi sisteminde bunu denemenin kolay bir yolu var. Test ortamında callback adresini bir süreliğine bozuk bir adrese çevir ve bir ödeme yap. Sonra şunlara bak: Sipariş ne durumda kaldı? Job onu ne zaman buldu? Biri bunu bir yerde gördü mü?

Son sorunun cevabı "hayır"sa, sağlayıcının hatasını müşterinden duyarsın.


Bu yazı ilk olarak huseyinbozdemir.com'da yayımlandı: https://huseyinbozdemir.com/blog/webhook-gelmezse

Top comments (0)