​
Webhook Entegrasyonu

Webhook, Hemen Mağaza içinde gerçekleşen olayları dış sistemlere HTTP isteğiyle bildiren mekanizmadır. Hemen Builders webhook yönetimi HemenHeadless teslimat çekirdeğini yeniden kullanır; Builders tarafı app, tenant, scope ve audit bağlamını sağlar.

​
Ne zaman webhook kullanılır?

  • Sipariş oluştuğunda ERP sistemine aktarmak.
  • Ödeme alındığında muhasebe entegrasyonunu tetiklemek.
  • Ürün veya stok değiştiğinde dış sistemi güncellemek.
  • Storefront veya admin app içinde gerçek zamanlı takip yapmak.

​
Desteklenen başlangıç eventleri

order.created
order.paid
order.cancelled
product.updated
stock.changed
Event kataloğu production kullanıma göre genişletilir. Endpoint yazarken bilinmeyen eventleri güvenli şekilde yok saymanız önerilir.

​
Endpoint ekleme

Tenant admin panelinde private app detayından veya Builders API üzerinden webhook endpoint’i ekleyebilirsiniz. Gerekenler:
  • App aktif olmalı.
  • App scope setinde webhooks:write bulunmalı.
  • Endpoint URL’i HTTPS olmalı.
  • Endpoint idempotent çalışmalı.
Örnek endpoint: 
https://example.com/webhooks/hemen
API örneği: 
curl -X POST "https://dev.hemenmagaza.com/api/builders/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "ERP Orders",
    "url": "https://example.com/webhooks/hemen",
    "events": ["order.created"],
    "max_attempts": 5
  }'
Response içindeki secret sadece oluşturma anında gösterilir.

​
Test delivery üretme

Webhook endpoint’inizi dış sisteme gerçek istek atmadan test etmek için imzalı test delivery oluşturabilirsiniz: 
curl -X POST "https://dev.hemenmagaza.com/api/builders/v1/webhooks/WEBHOOK_ID/test" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
    "event": "order.created",
    "payload": {
      "order_id": 123
    }
  }'
Bu endpoint HM-* header setini ve body örneğini döndürür. Production event gönderimleri HemenHeadless dispatcher ve queue üzerinden yapılır.

​
İmza header’ları

Webhook payload’ı standart HM-* header’ları ile gönderilir. 
HM-Event-Id
HM-Event-Type
HM-Tenant-Id
HM-Timestamp
HM-Signature
İmza doğrulama mantığı:
  1. HM-Timestamp değerinin kabul edilen zaman aralığında olduğunu kontrol edin.
  2. Request body ve timestamp ile beklenen HMAC SHA256 imzasını üretin.
  3. Beklenen imza ile HM-Signature değerini constant-time compare ile karşılaştırın.
  4. HM-Event-Id değerini idempotency anahtarı olarak saklayın.

​
Payload örneği

{
  "id": "evt_01HZ0000000000000000000000",
  "event": "order.created",
  "created_at": "2026-07-01T10:15:00Z",
  "tenant_id": "velunamora",
  "data": {
    "order_id": 9001,
    "status": "pending",
    "total": 1199.8,
    "currency": "TRY"
  }
}

​
Node.js doğrulama örneği

import crypto from "node:crypto";

export function verifyHemenWebhook({
  eventId,
  eventType,
  tenantId,
  rawBody,
  timestamp,
  signature,
  secret,
}) {
  const payload = [eventId, eventType, tenantId, timestamp, rawBody].join(".");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  const received = signature.startsWith("sha256=")
    ? signature.slice(7)
    : signature;

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

​
Retry ve delivery log

Webhook gönderimi başarısız olursa delivery kaydı retry kuyruğuna alınır. Delivery detaylarında şu bilgiler tutulur:
  • Request URL ve event tipi.
  • Attempt count.
  • Son response status/body özeti.
  • Hata mesajı.
  • Bir sonraki retry zamanı.
  • Dead-letter durumu.
Tenant admin panelinde webhook delivery listesi ve detay ekranı bulunur.

​
İyi endpoint davranışı

  • 2xx response sadece işlem kabul edildiyse dönülmelidir.
  • Aynı HM-Event-Id tekrar gelirse işlem ikinci kez uygulanmamalıdır.
  • Endpoint 5 saniye içinde yanıt vermelidir.
  • Ağır işlemler kendi kuyruğunuza alınmalıdır.
  • Signature hatasında 401 veya 403 dönülmelidir.

​
SDK helper

Hemen Builders SDK webhook signature helper sağlar. SDK detayları için Hemen SDK sayfasına bakın.