Webhooks

Webhook Events

BaZaaRDan webhook sistemi, sipariş, stok, kargo, iade ve benzeri olayları partner uygulamalara otomatik olarak gönderir. Böylece ERP veya muhasebe sistemleri sürekli sipariş sorgulamak zorunda kalmaz.

Webhook gönderimleri imzalıdır. Partner sistemler gelen istekteki imzayı doğrulamalıdır.

Webhook Flow

  1. BaZaaRDan içinde bir olay oluşur. Örnek: order.created
  2. Event seller_webhook_events kuyruğuna yazılır.
  3. Aktif webhook endpointler için delivery kayıtları oluşur.
  4. Cron worker pending delivery kayıtlarını işler.
  5. Partner webhook URL’sine imzalı POST gönderilir.
  6. 2xx cevap alınırsa delivery success olur.
  7. Tüm delivery’ler başarılıysa event sent olur.

Supported Events

Event Resource Açıklama
order.created order_item Yeni sipariş kalemi oluştuğunda gönderilir.
order.updated order_item Sipariş durumu veya temel bilgileri değiştiğinde gönderilir.
stock.updated product Ürün stoğu güncellendiğinde gönderilir.
shipment.updated shipment Kargo durumu değiştiğinde gönderilir.
return.requested return_request Müşteri iade talebi oluşturduğunda gönderilir.

Webhook Headers

Header Açıklama
Content-Type application/json
X-BZ-WEBHOOK-ID Delivery ID değeridir.
X-BZ-WEBHOOK-TIMESTAMP Unix timestamp değeridir.
X-BZ-WEBHOOK-SIGNATURE HMAC SHA256 webhook imzasıdır.
X-BZ-WEBHOOK-EVENT Event adıdır. Örnek: order.created

Payload Format

Webhook Payload
{
  "id": "evt_4",
  "type": "order.created",
  "resource_type": "order_item",
  "resource_id": 124,
  "seller_id": 5,
  "created_at": "2026-05-08 21:50:29",
  "data": {
    "order_item_id": 124,
    "message": "Test order.created event"
  }
}

Signature Verification

Webhook imzası aşağıdaki veri üzerinden oluşturulur:

Signing String
TIMESTAMP
WEBHOOK_ID
RAW_BODY_SHA256

Partner sistem, gelen request body’sini değiştirmeden ham haliyle okumalı ve aynı imzayı üretmelidir.

PHP Verification Example
<?php

$timestamp = $_SERVER["HTTP_X_BZ_WEBHOOK_TIMESTAMP"] ?? "";
$signature = $_SERVER["HTTP_X_BZ_WEBHOOK_SIGNATURE"] ?? "";

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

$expected = hash_hmac(
    "sha256",
    $timestamp . "." . $rawBody,
    $webhookSecret
);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    echo "Invalid signature";
    exit;
}

http_response_code(200);
echo "OK";

Node.js Verification Example

Node.js Verification
const crypto = require("crypto");

function verifyWebhook(req, rawBody, webhookSecret) {
  const timestamp = req.headers["x-bzr-webhook-timestamp"];
  const signature = req.headers["x-bzr-webhook-signature"];

  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Retry Policy

Partner endpoint 2xx dışında cevap verirse veya timeout olursa delivery tekrar denenir.

Deneme Bekleme Süresi
1. başarısızlık 5 dakika
2. başarısızlık 15 dakika
3. başarısızlık 60 dakika
Sonraki denemeler 180 dakika
Varsayılan maksimum deneme sayısı 5’tir. Maksimum deneme sonrası delivery failed durumunda kalır.

Status Lifecycle

pending Event veya delivery kuyruğa alınmıştır.
success Delivery partner endpointten 2xx cevap almıştır.
failed Maksimum deneme sonrası teslimat başarısız kalmıştır.
sent Event’in tüm delivery kayıtları başarıyla tamamlanmıştır.

Webhook Endpoint Requirements

Kural Açıklama
HTTPS zorunlu Production webhook URL mutlaka HTTPS olmalıdır.
2xx cevap Başarılı kabul edilmesi için 200-299 arası HTTP kodu dönmelidir.
Hızlı cevap Endpoint mümkünse 5 saniye içinde cevap vermelidir.
Idempotent işlem Aynı webhook tekrar gelebilir. Partner sistem duplicate kontrolü yapmalıdır.
Signature doğrulama Güvenlik için gelen imza kontrol edilmelidir.

Webhook.site ile Test

Test için webhook.site kullanılabilir.

Test Steps
1. https://webhook.site adresine girin.
2. Size özel URL oluşur.
3. Bu URL’yi Developer Portal webhook endpoint alanına girin.
4. Test event gönderin.
5. Gelen request içindeki headers ve body alanlarını kontrol edin.

Example Delivery Headers

Headers
Content-Type: application/json
X-BZ-WEBHOOK-ID: 12
X-BZ-WEBHOOK-TIMESTAMP: 1778267401
X-BZ-WEBHOOK-SIGNATURE: 4f6a...
X-BZ-WEBHOOK-EVENT: order.created

Security Notes

Webhook secret güvenli saklanmalıdır. Secret public frontend kodlarında, mobil uygulamalarda veya loglarda tutulmamalıdır.
Replay attack riskini azaltmak için timestamp çok eskiyse request reddedilmelidir. Önerilen tolerans: 5 dakika.

Idempotency & Duplicate Protection

Webhook deliveries may be retried multiple times. Partner systems must treat webhook consumers as idempotent.

The same webhook event may be delivered more than once. Always deduplicate using webhook event IDs and delivery IDs.
Field Purpose
event.id Globally unique webhook event ID
X-BZ-WEBHOOK-ID Unique delivery ID
event.type Webhook event category

Delivery Lifecycle

Status Description
pending Webhook delivery is queued.
retrying Previous delivery failed and retry is scheduled.
success Partner endpoint returned successful 2xx response.
failed Maximum retry attempts exceeded.
dead_letter Webhook moved to dead letter processing queue.

Webhook Security

Recommendation Reason
Always verify signatures Protects against forged webhook requests.
Use HTTPS endpoints only Protects webhook payloads in transit.
Process webhooks asynchronously Prevents timeout and retry storms.
Respond quickly with 2xx Webhook retries are triggered on slow responses.
Store processed event IDs Prevents duplicate processing.
Validate timestamps Protects against replay attacks.

Example Event Payloads

order.created

order.created
{
  "id": "evt_1001",
  "type": "order.created",
  "resource_type": "order_item",
  "resource_id": 124,
  "seller_id": 5,
  "created_at": "2026-05-08T21:50:29+03:00",
  "data": {
    "order_id": 55,
    "order_item_id": 124,
    "product_id": 933,
    "variant_combination_id": 441,
    "quantity": 1,
    "unit_price": 4200.00,
    "currency": "TRY"
  }
}

shipment.updated

shipment.updated
{
  "id": "evt_1002",
  "type": "shipment.updated",
  "resource_type": "shipment",
  "resource_id": 88,
  "seller_id": 5,
  "created_at": "2026-05-08T22:10:12+03:00",
  "data": {
    "shipment_ref": "BZ40T20260419231956",
    "tracking_number": "YT123456789",
    "carrier_code": "yurtici",
    "status": "out_for_delivery"
  }
}

stock.updated

stock.updated
{
  "id": "evt_1003",
  "type": "stock.updated",
  "resource_type": "product_variant_combination",
  "resource_id": 441,
  "seller_id": 5,
  "created_at": "2026-05-08T22:22:40+03:00",
  "data": {
    "product_id": 933,
    "variant_combination_id": 441,
    "variant_sku": "PRD-TUDERK-59288-LAC-XL-900-04",
    "old_stock": 100,
    "new_stock": 75
  }
}

Retry Strategy

BaZaaRDan webhook delivery system uses exponential backoff retry strategy.

Attempt Delay
1 5 minutes
2 15 minutes
3 60 minutes
4 180 minutes
5 720 minutes
Webhook endpoints should return a 2xx response as quickly as possible. Long-running processing should happen asynchronously.