Webhook Entegrasyonu

Genel Bakış

Ana platformda yönetici tarafından bir veri güncellendiğinde (örneğin bir randevu onaylandığında veya yeni bir blog yazısı eklendiğinde), bu değişikliğin harici sitenizde anında yansımasını sağlamak üzere web sitenizin webhook URL'ine bir HTTP POST isteği gönderilir.

Gönderilen tüm istekler, güvenliği sağlamak amacıyla HMAC-SHA256 imzalama yöntemi ile imzalanmaktadır. Alıcı sunucu, gelen isteğin gerçekten Randevu Ajandam sisteminden geldiğinden emin olmak için bu imzayı doğrulamalıdır.

Webhook İstek Yapısı

Gönderilen her webhook isteği aşağıdaki HTTP başlıklarını (headers) içerir:

Payload (Body) Yapısı

Webhook gövdesi JSON formatında gönderilir ve şu alanları içerir:

{
  "event": "blog.created",
  "timestamp": 1783003200,
  "data": {
    "id": 42,
    "baslik": "Yeni Sağlıklı Yaşam Kılavuzu",
    "slug": "yeni-saglikli-yasam-kilavuzu",
    "icerik": "Blog içeriği buraya gelir...",
    "durum": "yayinlandi",
    "created_at": "2026-07-03 13:28:00"
  }
}

İmza Doğrulama Algoritması

İmza doğrulaması için alıcı sunucunun yapması gereken adımlar şunlardır:

1. Gelen HTTP istek başlıklarından X-Timestamp ve X-Webhook-Signature değerlerini alın.
2. Gelen ham istek gövdesini (raw request body) olduğu gibi metin (string) olarak okuyun.
3. X-Timestamp değeri ile ham istek gövdesini sırayla birleştirin (Concatenate):
   payload = timestamp + rawBody
4. Bu birleşik metni, size tanımlanan Webhook Secret Key değerini kullanarak HMAC-SHA256 algoritmasından geçirin.
5. Ürettiğiniz imza ile X-Webhook-Signature başlığındaki imzayı karşılaştırın. Güvenlik için zamanlama saldırılarına karşı korumalı bir karşılaştırma fonksiyonu (hash_equals) kullanın.

Kod Örnekleri

Alıcı sunucuda imza doğrulamasını gerçekleştirecek örnek kod yapıları:

<?php

// 1. Webhook Secret Key değeriniz
$webhookSecret = 'YOUR_WEBHOOK_SECRET_KEY';

// 2. HTTP Başlıklarını Alın
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';

// 3. Ham İstek Gövdesini Okuyun
$rawBody = file_get_contents('php://input');

// 4. Zaman aşımı kontrolü (Replay Attack koruması için önerilen +/- 5 dk)
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(401);
    die('İstek zaman aşımı.');
}

// 5. İmzayı Hesaplayın
$payloadToSign = $timestamp . $rawBody;
$calculatedSignature = hash_hmac('sha256', $payloadToSign, $webhookSecret);

// 6. Güvenli Karşılaştırma Yapın
if (hash_equals($calculatedSignature, $signature)) {
    // İmza geçerli, isteği işleyebilirsiniz
    $data = json_decode($rawBody, true);
    $event = $data['event'];
    $modelData = $data['data'];
    
    // İş mantığınız...
    
    http_response_code(200);
    echo 'Başarılı';
} else {
    // Geçersiz imza
    http_response_code(401);
    echo 'Geçersiz imza.';
}

const crypto = require('crypto');
const express = require('express');
const app = express();

// Express raw body parser kullanımı önemlidir (imzalamada ham gövde kullanılır)
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook-receiver', (req, res) => {
    const webhookSecret = 'YOUR_WEBHOOK_SECRET_KEY';
    
    const signature = req.headers['x-webhook-signature'];
    const timestamp = req.headers['x-timestamp'];
    const rawBody = req.body.toString('utf8');
    
    if (!signature || !timestamp) {
        return res.status(401).send('Eksik başlıklar.');
    }
    
    // Zaman aşımı kontrolü
    if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
        return res.status(401).send('İstek zaman aşımı.');
    }
    
    // İmza hesapla
    const payloadToSign = timestamp + rawBody;
    const calculatedSignature = crypto
        .createHmac('sha256', webhookSecret)
        .update(payloadToSign)
        .digest('hex');
        
    // Güvenli karşılaştırma
    try {
        if (crypto.timingSafeEqual(Buffer.from(calculatedSignature), Buffer.from(signature))) {
            const data = JSON.parse(rawBody);
            console.log(`Olay tetiklendi: ${data.event}`);
            
            // İş mantığınız...
            
            res.status(200).send('Başarılı');
        } else {
            res.status(401).send('Geçersiz imza.');
        }
    } catch (e) {
        res.status(401).send('Doğrulama hatası.');
    }
});