Webhook Consumer

Paylox'tan gelen webhook bildirimlerini dinleyen, doğrulayan ve işleyen bir endpoint yazma rehberi.

Temel Yapı

Node.js (Express)

const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhooks/paylox", async (req, res) => {
  const { event, data } = req.body;

  const existing = await db.webhookLogs.findOne({ order_id: data.order_id, event });
  if (existing) {
    return res.status(200).json({ received: true });
  }

  await db.webhookLogs.insertOne({
    order_id: data.order_id,
    event,
    payload: req.body,
    processed_at: new Date()
  });

  switch (event) {
    case "payment.completed":
      await handlePaymentCompleted(data);
      break;
    case "payment.failed":
      await handlePaymentFailed(data);
      break;
    case "refund.completed":
      await handleRefundCompleted(data);
      break;
  }

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

async function handlePaymentCompleted(data) {
  await Order.updateOne(
    { ref: data.order_id },
    { status: "paid", paid_at: new Date() }
  );
}

async function handlePaymentFailed(data) {
  await Order.updateOne(
    { ref: data.order_id },
    { status: "payment_failed", error: data.message }
  );
}

async function handleRefundCompleted(data) {
  await Order.updateOne(
    { ref: data.order_id },
    { status: "refunded", refunded_at: new Date() }
  );
}

Python (Django)

import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST

@csrf_exempt
@require_POST
def paylox_webhook(request):
    payload = json.loads(request.body)
    event = payload.get("event")
    data = payload.get("data", {})

    existing = WebhookLog.objects.filter(
        order_id=data.get("order_id"),
        event=event
    ).exists()

    if existing:
        return JsonResponse({"received": True})

    WebhookLog.objects.create(
        order_id=data.get("order_id"),
        event=event,
        payload=payload
    )

    handlers = {
        "payment.completed": handle_payment_completed,
        "payment.failed": handle_payment_failed,
        "refund.completed": handle_refund_completed,
    }

    handler = handlers.get(event)
    if handler:
        handler(data)

    return JsonResponse({"received": True})

Önemli Kurallar

Kural	Açıklama
Hızlı yanıt	5 saniye içinde HTTP 200 döndürün
İdempotent	Aynı event birden fazla gelirse tekrar işlemeyin
Loglama	Her webhook'u veritabanına kaydedin
Asenkron işlem	Ağır işlemleri queue'ya atın, hemen 200 döndürün