Webhook Nedir ve Nasıl Çalışır?

Webhook, bir uygulamada belirli bir olay gerçekleştiğinde başka bir uygulamaya otomatik olarak HTTP isteği gönderilmesini sağlayan bir iletişim mekanizmasıdır.

Webhook sistemleri, farklı yazılımların birbirleriyle olay tabanlı şekilde iletişim kurmasını sağlar. Özellikle ödeme sistemleri, e-ticaret uygulamaları, mesajlaşma platformları, otomasyon servisleri ve üçüncü taraf API entegrasyonlarında kullanılır.

Örneğin bir e-ticaret sitesinde ödeme tamamlandığında ödeme sağlayıcısı, mağazanın sunucusuna otomatik olarak bildirim gönderebilir. Mağaza uygulaması bu bildirimi işleyerek siparişin ödeme durumunu güncelleyebilir.

Webhook mekanizmasının temel amacı, uygulamaların belirli olaylardan haberdar olmak için sürekli API isteği göndermek zorunda kalmasını azaltmaktır.

Webhook Ne İşe Yarar?

Webhook, farklı uygulamalar arasında otomatik olay bildirimleri oluşturmak için kullanılır.

Başlıca kullanım alanları şunlardır:

• Ödeme tamamlandığında ilgili uygulamaya bildirim göndermek.

• Yeni sipariş oluşturulduğunda stok veya muhasebe sistemini bilgilendirmek.

• Bir kullanıcı kaydı gerçekleştiğinde başka bir serviste işlem başlatmak.

• Kod deposuna yeni değişiklik gönderildiğinde otomatik dağıtım sürecini tetiklemek.

• Form gönderildiğinde CRM sistemine veri aktarmak.

• Kargo durumu değiştiğinde sipariş sistemini güncellemek.

• Mesajlaşma uygulamalarından gelen olayları işlemek.

• Farklı yazılımlar arasında otomasyon süreçleri oluşturmak.

Webhook, uygulamaların olaylara bağlı olarak otomatik işlem gerçekleştirmesini sağlar.

Webhook Nasıl Çalışır?

Webhook sistemlerinde genellikle olayları oluşturan bir uygulama ve bu olayları alan başka bir uygulama bulunur.

Temel çalışma süreci şu şekildedir:

1. Webhook gönderen uygulamada belirli bir olay gerçekleşir.

2. Uygulama, olayla ilgili bir bildirim oluşturur.

3. Bildirim, önceden tanımlanan webhook adresine HTTP isteğiyle gönderilir.

4. Alıcı sunucu gelen isteği kabul eder.

5. İsteğin kaynağı ve bütünlüğü doğrulanır.

6. Gelen veri işlenir.

7. Gerekli veritabanı veya uygulama işlemleri gerçekleştirilir.

8. Alıcı sunucu uygun bir HTTP yanıtı döndürür.

Webhook bildirimleri çoğunlukla HTTP POST metoduyla gönderilir. Ancak kullanılan yöntem ve veri biçimi hizmet sağlayıcısına göre değişebilir.

Webhook Endpoint Nedir?

Webhook Endpoint, başka bir uygulamadan gönderilen olay bildirimlerini kabul eden HTTP adresidir.

Örneğin:

 https://example.com/api/webhooks/payment 

Bu adres, ödeme sistemi tarafından gönderilen bildirimleri almak için kullanılabilir.

Örnek HTTP isteği:

POST /api/webhooks/payment HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "event": "payment.completed",
  "payment_id": "pay_12345",
  "order_id": "ORD-1001",
  "status": "completed"
}

Bu örnekte ödeme tamamlandığında sunucuya bir bildirim gönderilmektedir.

Webhook adresinin erişilebilir olması, isteğin otomatik olarak güvenilir kabul edilmesi anlamına gelmez. Gelen bildirimlerin ayrıca doğrulanması gerekir.

Webhook ile API Arasındaki Farklar

Webhook ve API, uygulamalar arasında veri alışverişi yapılmasını sağlayabilir. Ancak çalışma yöntemleri farklıdır.

Webhook, API teknolojilerinin yerine geçen ayrı bir iletişim protokolü değildir. Genellikle HTTP API mekanizmalarını kullanarak olay bildirimleri gönderir.

Webhook ile Polling Arasındaki Farklar

Polling, bir uygulamanın başka bir sistemde değişiklik olup olmadığını belirli aralıklarla sorgulamasıdır.

Örneğin bir uygulama her 30 saniyede bir ödeme durumunu kontrol edebilir.

Webhook sisteminde ise ödeme sağlayıcısı, ilgili olay gerçekleştiğinde bildirim gönderir.

Webhook kullanılması, olayların her zaman anında veya kesin olarak teslim edileceği anlamına gelmez.

Webhook Payload Nedir?

Payload, webhook isteğinin gövdesinde taşınan veridir.

Webhook sağlayıcıları çoğunlukla JSON biçimini kullanır.

Örnek:

{
  "id": "evt_10001",
  "type": "order.created",
  "created_at": "2026-11-11T10:30:00Z",
  "data": {
    "order_id": 1501,
    "customer_id": 42,
    "total": 1250,
    "currency": "TRY"
  }
}

Bu örnekte:

• id: Olayın tanımlayıcısıdır.

• type: Olayın türünü belirtir.

• created_at: Olayın oluşturulma zamanını gösterir.

• data: Olayla ilgili bilgileri içerir.

Payload yapısı her webhook sağlayıcısında aynı değildir.

Webhook Event Nedir?

Event, webhook gönderimini tetikleyen olaydır.

Örneğin bir e-ticaret sisteminde aşağıdaki olay türleri bulunabilir:

Bu olay adları örnektir. Gerçek sistemlerde farklı isimlendirmeler kullanılabilir.

PHP ile Webhook Nasıl Oluşturulur?

PHP kullanılarak webhook bildirimlerini kabul eden bir endpoint hazırlanabilir.

Aşağıdaki örnek, JSON biçiminde gelen bir webhook isteğinin temel olarak nasıl alınacağını gösterir.

<?php

header('Content-Type: application/json');

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);

    echo json_encode([
        'error' => 'Method not allowed'
    ]);

    exit;
}

$rawBody = file_get_contents('php://input');

$data = json_decode($rawBody, true);

if (!is_array($data)) {
    http_response_code(400);

    echo json_encode([
        'error' => 'Invalid JSON'
    ]);

    exit;
}

$event = $data['type'] ?? null;

if ($event === 'order.created') {
    // Sipariş olayı işlenir.
}

http_response_code(200);

echo json_encode([
    'received' => true
]);

Bu örnek yalnızca webhook isteğinin alınmasını ve JSON verisinin okunmasını göstermektedir.

Gerçek bir uygulamada gelen webhook isteği doğrulanmadan sipariş, ödeme veya kullanıcı verileri değiştirilmemelidir. İmza doğrulaması, olay kimliği kontrolü ve güvenli işlem yönetimi eklenmelidir.

Node.js Express ile Webhook Oluşturma

Node.js Express kullanılarak webhook endpoint oluşturulabilir.

Öncelikle Express kurulur:

npm install express

Örnek:

const express = require("express");

const app = express();

app.post(
    "/webhook",
    express.json(),
    (req, res) => {
        const event = req.body.type;

        if (event === "order.created") {
            console.log("Yeni sipariş olayı alındı.");
        }

        res.status(200).json({
            received: true
        });
    }
);

app.listen(3000, () => {
    console.log("Webhook sunucusu çalışıyor.");
});

Bu örnekte /webhook adresine gönderilen JSON verisi alınmaktadır.

Kod, temel işleyişi göstermek içindir ve güvenli bir üretim ortamı webhook uygulaması olarak kullanılmamalıdır.

İmza doğrulaması gereken webhook sistemlerinde ham istek gövdesinin korunması önemlidir. Bazı sağlayıcıların imza doğrulama yöntemleri, JSON ayrıştırılmadan önce alınan ham veri üzerinden çalışır.

Python Flask ile Webhook Oluşturma

Python Flask ile de webhook endpoint hazırlanabilir.

Örnek:

from flask import Flask, request, jsonifyapp = Flask(__name__)@app.route("/webhook", methods=["POST"])def webhook():    data = request.get_json(silent=True)    if not isinstance(data, dict):        return jsonify({            "error": "Invalid JSON"        }), 400    event = data.get("type")    if event == "order.created":        print("Yeni sipariş bildirimi alındı.")    return jsonify({        "received": True    }), 200if __name__ == "__main__":    app.run(debug=True)

Bu örnekte Flask uygulaması POST isteğiyle gelen JSON verisini okur.

debug=True yalnızca geliştirme ortamında kullanılmalıdır.

Webhook Güvenliği Nasıl Sağlanır?

Webhook endpoint adresleri dış sistemlerden HTTP isteği kabul ettiği için güvenlik kontrolleri gerektirir.

Önemli güvenlik önlemleri şunlardır:

• HTTPS kullanılması.

• Gelen webhook imzasının doğrulanması.

• İstek gövdesinin güvenli şekilde işlenmesi.

• Olay türlerinin kontrol edilmesi.

• Tekrarlanan olayların tespit edilmesi.

• İstek boyutunun sınırlandırılması.

• Gerektiğinde IP kısıtlaması uygulanması.

• Gizli anahtarların güvenli saklanması.

• Hata kayıtlarının tutulması.

• Yetkisiz işlemlerin engellenmesi.

Webhook adresinin gizli tutulması tek başına yeterli bir güvenlik önlemi değildir.

Webhook Signature Nedir?

Webhook Signature, gönderilen bildirimin kaynağını ve içeriğinin bütünlüğünü doğrulamak amacıyla kullanılan kriptografik imzadır.

Birçok webhook sağlayıcısı HMAC gibi mekanizmalar kullanır.

Genel çalışma mantığı şöyledir:

1. Webhook sağlayıcısı ve alıcı uygulama ortak bir gizli anahtar kullanır.

2. Sağlayıcı, belirlenen veri üzerinden kriptografik imza oluşturur.

3. İmza HTTP başlığında gönderilir.

4. Alıcı sunucu aynı kurallarla beklenen imzayı hesaplar.

5. İmzalar güvenli şekilde karşılaştırılır.

6. Doğrulama başarısızsa bildirim reddedilir.

PHP ile HMAC İmza Doğrulama

Aşağıdaki örnek, ham istek gövdesi üzerinden HMAC-SHA256 imzası doğrulayan temsili bir webhook protokolünü göstermektedir.

<?php

$secret = getenv('WEBHOOK_SECRET');

if (!$secret) {
    http_response_code(500);
    exit;
}

$payload = file_get_contents('php://input');

$receivedSignature =
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expectedSignature = hash_hmac(
    'sha256',
    $payload,
    $secret
);

if (!hash_equals(
    $expectedSignature,
    $receivedSignature
)) {
    http_response_code(401);
    exit;
}

http_response_code(200);

echo json_encode([
    'verified' => true
]);

Bu örnek, sağlayıcının X-Webhook-Signature başlığında düz hexadecimal HMAC-SHA256 değeri gönderdiğini varsayar.

Gerçek webhook sağlayıcıları farklı imza biçimleri, zaman damgaları ve doğrulama kuralları kullanabilir. Bu nedenle uygulama, ilgili sağlayıcının imza doğrulama yöntemine uygun hazırlanmalıdır.

Webhook Replay Attack Nedir?

Replay Attack, daha önce gönderilmiş geçerli bir webhook isteğinin yeniden gönderilmesiyle gerçekleştirilen saldırı türüdür.

Örneğin ödeme tamamlandı bildirimi tekrar gönderilirse, yeterli kontroller bulunmayan bir sistem aynı işlemi birden fazla kez gerçekleştirebilir.

Bu riski azaltmak için:

• Olay kimlikleri saklanabilir.

• Daha önce işlenen olaylar yeniden işlenmeyebilir.

• Sağlayıcının desteklediği zaman damgası kontrolleri uygulanabilir.

• İmzalı zaman bilgileri doğrulanabilir.

• Veritabanı işlemleri idempotent tasarlanabilir.

Yalnızca geçerli imza kontrolü yapılması, aynı geçerli bildirimin tekrar kullanılmasını her zaman engellemez.

Webhook Idempotency Nedir?

Idempotency, aynı işlemin birden fazla kez gerçekleştirilmesi durumunda sistemin istenmeyen tekrar etkiler üretmemesini sağlayan yaklaşımdır.

Webhook sistemlerinde aynı olay birden fazla kez gönderilebilir.

Örneğin:

{
  "id": "evt_5001",
  "type": "payment.completed",
  "data": {
    "order_id": 120
  }
}

Aynı evt_5001 olayı yeniden gönderildiğinde sistem daha önce işlendiğini tespit edebilir.

Bu amaçla olay kimliği veritabanında benzersiz olarak saklanabilir.

Özellikle ödeme, stok ve sipariş işlemlerinde idempotency önemlidir.

Webhook Retry Mekanizması Nedir?

Retry, başarısız webhook teslimatlarının yeniden denenmesidir.

Örneğin alıcı sunucu geçici olarak erişilemiyorsa webhook sağlayıcısı bildirimi daha sonra yeniden gönderebilir.

Yeniden deneme davranışı sağlayıcıya bağlıdır.

Bazı sağlayıcılar:

• Belirli sayıda yeniden deneme yapar.

• Denemeler arasında bekleme süresi uygular.

• Artan bekleme süreleri kullanır.

• Başarısız bildirimleri kayıt altına alır.

• Yönetim panelinden yeniden gönderime izin verir.

Bütün webhook sağlayıcılarının aynı retry politikasını uyguladığı varsayılmamalıdır.

Webhook HTTP Durum Kodları

Webhook alıcıları, gönderilen isteğe HTTP durum koduyla yanıt verir.

Webhook sağlayıcısının hangi durum kodlarını başarılı teslimat olarak kabul ettiği ve hangi kodlarda yeniden deneme yaptığı kendi politikasına bağlıdır.

Webhook ile Ödeme Sistemi Entegrasyonu

Webhook kullanımının yaygın örneklerinden biri ödeme sistemleridir.

Bir ödeme süreci genel olarak şu şekilde ilerleyebilir:

1. Kullanıcı e-ticaret sitesinde ödeme başlatır.

2. Ödeme sağlayıcısı işlemi gerçekleştirir.

3. Ödeme sonucuna ilişkin bir olay oluşur.

4. Sağlayıcı, mağazanın webhook adresine bildirim gönderir.

5. Mağaza sunucusu bildirimin imzasını doğrular.

6. İlgili ödeme ve sipariş kayıtları kontrol edilir.

7. Ödeme tutarı, para birimi ve işlem kimliği doğrulanır.

8. Sipariş durumu güvenli şekilde güncellenir.

Ödeme sistemlerinde yalnızca istemcinin ödeme başarılı mesajına güvenilmemelidir.

Webhook bildiriminin doğrulanması ve gerekli durumlarda ödeme sağlayıcısının API'si üzerinden işlem durumunun kontrol edilmesi önemlidir.

Webhook ile GitHub Entegrasyonu

GitHub gibi kod barındırma platformları, depo olayları için webhook desteği sunabilir.

Örneğin bir depoya yeni kod gönderildiğinde webhook tetiklenebilir.

Bu olay üzerinden:

• Otomatik testler başlatılabilir.

• CI/CD süreçleri çalıştırılabilir.

• Dağıtım işlemleri tetiklenebilir.

• Ekip bildirimleri oluşturulabilir.

• Kod analiz sistemleri bilgilendirilebilir.

Webhook, yazılım geliştirme otomasyonlarında kullanılan önemli mekanizmalardan biridir.

Webhook ile Mikroservis İletişimi

Mikroservis mimarisinde farklı servislerin olaylardan haberdar olması gerekebilir.

Örneğin sipariş servisi yeni bir sipariş oluşturduğunda stok servisine bildirim gönderebilir.

Bu yaklaşım olay tabanlı iletişim kurulmasına yardımcı olur.

Ancak webhook kullanımı her durumda mesaj kuyruğu veya olay aracısı sistemlerinin yerini almaz.

Yüksek hacimli ve güvenilir teslimat gerektiren sistemlerde RabbitMQ, Apache Kafka veya benzeri mesajlaşma altyapıları da değerlendirilebilir.

Webhook ile WebSocket Arasındaki Farklar

Webhook ve WebSocket farklı iletişim ihtiyaçları için kullanılır.

Webhook, özellikle farklı sunucular arasında olay bildirimi için uygundur.

WebSocket ise sürekli ve çift yönlü veri iletişimi gereken uygulamalarda kullanılabilir.

Webhook Testleri Nasıl Yapılır?

Webhook endpoint'leri geliştirme aşamasında test edilmelidir.

Testlerde şu durumlar kontrol edilebilir:

1. Geçerli webhook isteğinin kabul edilmesi.

2. Hatalı JSON verisinin reddedilmesi.

3. Geçersiz imzanın reddedilmesi.

4. Aynı olayın tekrar gönderilmesi.

5. Bilinmeyen olay türlerinin işlenmesi.

6. Sunucu hatalarında uygun HTTP yanıtı verilmesi.

7. Uzun süren işlemlerin doğru yönetilmesi.

8. Olay kayıtlarının tutulması.

Postman gibi araçlar kullanılarak webhook endpoint'lerine örnek HTTP istekleri gönderilebilir.

Ancak gerçek entegrasyon testlerinde webhook sağlayıcısının sunduğu test veya sandbox ortamının kullanılması da önemlidir.

Webhook Kullanmanın Avantajları

Webhook sistemlerinin başlıca avantajları şunlardır:

Olay tabanlı çalışma: Belirli olaylar gerçekleştiğinde otomatik bildirim gönderilebilir.

Daha az gereksiz sorgu: Sürekli API sorgulama ihtiyacı azaltılabilir.

Entegrasyon kolaylığı: Farklı uygulamalar HTTP üzerinden iletişim kurabilir.

Otomasyon desteği: Olaylara bağlı iş süreçleri başlatılabilir.

Esnek kullanım: Ödeme, sipariş, kargo ve yazılım geliştirme sistemlerinde kullanılabilir.

Düşük bildirim gecikmesi: Sağlayıcının altyapısına bağlı olarak olaylar kısa sürede iletilebilir.

Webhook Kullanmanın Dezavantajları

Webhook kullanımında bazı zorluklar bulunmaktadır.

Teslimat Garantisi

Webhook bildiriminin her zaman başarılı şekilde teslim edileceği garanti değildir.

Tekrarlanan Bildirimler

Aynı olay birden fazla kez gönderilebilir.

Güvenlik Gereksinimleri

Webhook endpoint'lerinin imza doğrulaması ve diğer güvenlik kontrolleriyle korunması gerekir.

Olay Sıralaması

Farklı webhook bildirimleri her zaman oluşturuldukları sırayla ulaşmayabilir.

Erişilebilir Sunucu Gereksinimi

Webhook alıcısının, sağlayıcının istek gönderebileceği erişilebilir bir endpoint sunması gerekir.

Webhook Kullanılırken Yapılan Yaygın Hatalar

Webhook geliştirme süreçlerinde karşılaşılan hatalar şunlardır:

• Gelen her HTTP isteğine güvenmek.

• Webhook imzasını doğrulamamak.

• Aynı olayı birden fazla kez işlemek.

• Gelen verileri kontrol etmeden veritabanına kaydetmek.

• Ödeme bildirimlerinde işlem tutarını doğrulamamak.

• Webhook endpoint'inde gereğinden uzun işlemler çalıştırmak.

• Hata durumlarını kayıt altına almamak.

• Yeniden gönderilen bildirimleri hesaba katmamak.

• Olayların her zaman sırayla geleceğini varsaymak.

• Gizli webhook anahtarlarını kaynak kodunda saklamak.

Bu hatalar veri tutarsızlığına, yetkisiz işlemlere veya entegrasyon sorunlarına yol açabilir.

Webhook Hangi Alanlarda Kullanılır?

Webhook farklı yazılım sistemlerinde kullanılabilir.

E-ticaret: Sipariş ve ödeme bildirimleri.

Ödeme sistemleri: İşlem sonucu ve ödeme durumu güncellemeleri.

Kargo entegrasyonları: Gönderi ve teslimat durumu değişiklikleri.

CRM uygulamaları: Yeni müşteri veya form bildirimleri.

Yazılım geliştirme: Kod deposu olayları ve CI/CD otomasyonları.

Mesajlaşma platformları: Mesaj ve olay bildirimleri.

Bulut hizmetleri: Kaynak değişiklikleri ve otomasyon tetikleyicileri.

Kurumsal uygulamalar: Farklı sistemler arasında olay tabanlı veri aktarımı.

Sonuç

Webhook, bir uygulamada belirli bir olay gerçekleştiğinde başka bir uygulamaya otomatik HTTP isteği gönderilmesini sağlayan iletişim mekanizmasıdır.

API sistemleriyle birlikte kullanılan webhook yapıları, uygulamalar arasında olay tabanlı entegrasyonlar kurulmasına yardımcı olur.

Ödeme bildirimleri, sipariş güncellemeleri, kargo hareketleri, yazılım geliştirme otomasyonları ve kurumsal entegrasyonlar webhook kullanımının yaygın örnekleridir.

Güvenli bir webhook sistemi oluşturmak için gelen isteklerin doğrulanması, tekrarlanan olayların kontrol edilmesi, hata durumlarının yönetilmesi ve uygun yeniden deneme mekanizmalarının uygulanması gerekir.

Webhook sistemleri doğru yapılandırıldığında farklı uygulamaların daha az gereksiz sorguyla ve daha otomatik biçimde birlikte çalışmasını sağlayabilir.