Webhook'lar

Bu belge TrustChex sistemindeki webhook işlevselliğini açıklamaktadır.

Genel Bakış

Webhook'lar, TrustChex hesabınızda gerçekleşen olaylar hakkında uygulamanızın gerçek zamanlı bildirimleri almasını sağlar. Bir olay meydana geldiğinde, yapılandırılmış webhook URL'sine bir HTTP POST isteği gönderiyoruz.

Temel Özellikler:

• Gerçek zamanlı olay bildirimleri
• Üstel geri çekilme ile otomatik yeniden deneme mekanizması
• Güvenlik için HMAC SHA256 imza doğrulama
• Kapsamlı olay günlüğü ve izleme
• Kolay hata ayıklama için test işlevselliği

Olay Türleri

Doğrulama Oturumu Olayları

• verification_session.created - Yeni bir doğrulama oturumu oluşturuldu
• verification_session.completed - Doğrulama oturumu tamamlandı
• verification_session.cancelled - Doğrulama oturumu iptal edildi

Kimlik Doğrulama Olayları

• identification.created - Yeni bir kimlik doğrulama oluşturuldu
• identification.submitted - Kimlik doğrulama inceleme için gönderildi
• identification.failed - Kimlik doğrulama işlemi başarısız oldu
• identification.in_automatic_review - Kimlik doğrulama otomatik inceleme altında
• identification.in_manual_review - Kimlik doğrulama manuel inceleme gerektiriyor
• identification.waiting_for_status_change_approval - Durum değişikliği onay bekliyor
• identification.approved - Kimlik doğrulama onaylandı
• identification.rejected - Kimlik doğrulama reddedildi
• identification.resubmission_required - Kimlik doğrulama yeniden gönderim gerektiriyor

Webhook Yönetimi

Webhook Oluşturma

1. Panonuzda Ayarlar > Webhook'lar bölümüne gidin
2. "Yeni Webhook" butonuna tıklayın
3. Webhook'unuzu yapılandırın:
   • URL: Webhook olaylarını almak istediğiniz uç nokta
   • Açıklama: Webhook'unuz için isteğe bağlı açıklama
   • Olaylar: Abone olmak istediğiniz olay türlerini seçin
   • Aktif: Webhook'u etkinleştirin/devre dışı bırakın
4. Webhook'unuzu oluşturmak için "Kaydet" butonuna tıklayın

Webhook'ları Test Etme

Uç noktanızı doğrulamak için webhook panosundaki test butonunu kullanın:

1. Webhook'unuzun yanındaki Test butonuna tıklayın
2. Uç noktanıza bir test olayı gönderilecek
3. Teslimat durumunu görmek için olay günlüklerini kontrol edin
4. Hata ayıklama için istek/yanıt ayrıntılarını inceleyin

Webhook Yükü

Tüm webhook'lar aşağıdaki standart alanları içerir:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "hesap-id-niz",
  "webhookId": "webhook-id",
  "eventType": "identification.approved",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "data": {
    "accountId": "hesap-id-niz",
    "identificationId": "kimlik-dogrulama-id",
    "status": "APPROVED",
    "email": "kullanici@ornek.com",
    "phoneNumber": "+1234567890",
    "score": 95,
    "createdAt": "2024-01-01T11:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Olaya Özel Yük Örnekleri

Doğrulama Oturumu Veri Yapısı

{
  "data": {
    "accountId": "hesap-id-niz",
    "sessionId": "oturum-id",
    "status": "COMPLETED",
    "identificationId": "kimlik-dogrulama-id",
    "email": "kullanici@ornek.com",
    "phoneNumber": "+1234567890",
    "locale": "tr",
    "sendOTP": true,
    "createdAt": "2024-01-01T11:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z",
    "expiresAt": "2024-01-01T13:00:00.000Z"
  }
}

Kimlik Doğrulama Veri Yapısı

{
  "data": {
    "accountId": "hesap-id-niz",
    "identificationId": "kimlik-dogrulama-id",
    "status": "APPROVED",
    "email": "kullanici@ornek.com",
    "phoneNumber": "+1234567890",
    "score": 95,
    "createdAt": "2024-01-01T11:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Başlıklar

Her webhook isteği şu başlıkları içerir:

• Content-Type: application/json
• User-Agent: TrustChex-Webhook/1.0
• X-Webhook-Event: {eventType}
• X-Webhook-Delivery: {deliveryId}
• X-Webhook-Timestamp: {timestamp}
• X-Webhook-Secret: {secret} (yapılandırılmışsa)
• X-Webhook-Signature-256: sha256={signature} (gizli anahtar yapılandırılmışsa)

Güvenlik

Gizli Anahtar Doğrulama

Webhook'unuz için bir gizli anahtar yapılandırırsanız, bunu X-Webhook-Secret başlığına dahil ederiz ve X-Webhook-Signature-256 başlığında bir HMAC SHA256 imzası oluştururuz.

İmzayı doğrulamak için:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Teslimat ve Yeniden Denemeler

• Webhook'ların 30 saniyelik zaman aşımı vardır
• Başarısız teslimatlar üstel geri çekilme ile en fazla 3 kez yeniden denenir (1s, 3s, 9s)
• HTTP durum kodları 2xx başarılı olarak kabul edilir
• Tüm webhook denemeleri günlüğe kaydedilir ve panoda görüntülenebilir

Test Etme

Uç noktanıza bir test olayı göndermek için webhook panosundaki test işlevselliğini kullanın:

{
  "id": "test-teslimat-id",
  "accountId": "hesap-id-niz",
  "webhookId": "webhook-id-niz",
  "eventType": "test.webhook",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "data": {
    "message": "Bu bir test webhook teslimatıdır",
    "test": true
  }
}

Test Uç Noktası

Test amaçları için, genel webhook uç noktamızı kullanabilirsiniz:

https://domain-adresiniz.com/api/public/webhooks

Sorgu parametreleri:

• ?fail=true - Başarısızlığı simüle eder (500 döndürür)
• ?status=404 - Belirli durum kodu döndürür
• ?delay=5000 - Milisaniye cinsinden gecikme ekler (maksimum 60000)

En İyi Uygulamalar

1. İdempotentlik: Yinelenen olayları işlemekten kaçınmak için webhook teslimat ID'sini kullanın
2. Zaman Aşımı Yönetimi: Zaman aşımlarını önlemek için 30 saniye içinde yanıt verin
3. Hata Yönetimi: Uygun HTTP durum kodları döndürün (başarı için 2xx)
4. Güvenlik: Gizli anahtarlar kullanırken her zaman webhook imzalarını doğrulayın
5. Günlük Kayıtları: Hata ayıklama ve izleme için webhook olaylarını günlüğe kaydedin
6. Zarif Bozulma: Uygulamanızda webhook hatalarını zarif bir şekilde yönetin

Örnek Uygulamalar

Node.js Express

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

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature-256'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (secret && signature) {
    const payload = JSON.stringify(req.body);
    const expectedSignature = 'sha256=' + crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
    
    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      return res.status(401).send('Yetkisiz');
    }
  }
  
  console.log('Webhook alındı:', req.body);
  
  // Webhook olayını işle
  switch (req.body.eventType) {
    case 'identification.approved':
      // Onay işlemini yönet
      break;
    case 'identification.rejected':
      // Red işlemini yönet
      break;
    default:
      console.log('Bilinmeyen olay türü:', req.body.eventType);
  }
  
  res.json({ received: true });
});

Python Flask

import hmac
import hashlib
import json
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature-256')
    secret = os.environ.get('WEBHOOK_SECRET')
    
    if secret and signature:
        payload = request.get_data()
        expected_signature = 'sha256=' + hmac.new(
            secret.encode('utf-8'),
            payload,
            hashlib.sha256
        ).hexdigest()
        
        if not hmac.compare_digest(signature, expected_signature):
            return jsonify({'error': 'Yetkisiz'}), 401
    
    data = request.get_json()
    print(f"Webhook alındı: {data}")
    
    # Webhook olayını işle
    event_type = data.get('eventType')
    if event_type == 'identification.approved':
        # Onay işlemini yönet
        pass
    elif event_type == 'identification.rejected':
        # Red işlemini yönet
        pass
    
    return jsonify({'received': True})