Webhook'lar

Webhook'lar, mağazada bir olay olduğunda (sipariş ödendi, ürün güncellendi, müşteri oluşturuldu…) Tecof'un uygulamanıza imzalı bir POST isteği göndermesidir. Platform uygulamaları ayrıca kurulum, kaldırma, kapsam, abonelik ve ayar değişikliklerini bildiren yaşam döngüsü olaylarını abonelik gerekmeden alır.

Abonelik#

Abonelik tecof.app.json içinde tanımlanır:

{
  "scopes": ["orders:read", "customers:read"],
  "webhooks": {
    "path": "/api/webhooks",
    "events": ["order.paid", "order.cancelled", "order.refunded", "customer.created"]
  }
}

• path, appUrl'e göredir ve / ile başlar. Teslimat adresi: appUrl + webhooks.path. Test mağazası kurulumlarında, tecof app dev açıksa appUrl yerine tünel adresi (devUrl) kullanılır; adres teslimat anında çözülür.
• webhooks.path tanımlı değilse yaşam döngüsü olayları (app.installed, app.uninstalled…) ve uygulama olayları da teslim edilemez. Mağaza olayı dinlemeseniz bile path tanımlayın.
• Her olayın gerektirdiği okuma kapsamı scopes içinde olmalıdır; aksi hâlde yapılandırma reddedilir.
• * (tüm olaylar) jokeri uygulamalara kapalıdır.
• Mağaza uygulamayı kurduğunda abonelik otomatik açılır. Yapılandırma değişince abonelik eşitlenir: etkin olaylar, yapılandırmadaki olaylarla mağazanın verdiği kapsamların kesişimidir.

Olay Kataloğu ve Gereken Kapsam#

Başka uygulamaların yayınladığı app.<slug>.<ad> olayları da aynı biçimde teslim edilir; bkz. Uygulamalar Arası İletişim.

Yaşam Döngüsü Olayları#

Bu olaylar her zaman gönderilir; webhooks.events içinde listelenmeleri gerekmez.

app.uninstalled: Kurulumun token'ları bu teslimat bittikten sonra iptal edilir; işleyiciniz 8 saniye içinde Tecof API'sini hâlâ çağırabilir (ör. son durumu okumak için). Teslimattan sonra kurulum kaldırılır, kurulumun ayarları ve sırları silinir. Olay yeniden denenmez; kaçırırsanız temizliği bir sonraki API çağrısında aldığınız 401 ile tetikleyin.

app.settings.updated yalnız mağaza paneldeki ayar formunu kaydettiğinde gelir; uygulamanızın PUT /api/v1/app/settings ile yaptığı yazmalar bu olayı üretmez. Olay değer taşımaz: değişen ayarları api.settings.get() ve api.secrets.get(key) ile okuyun.

Teslimat Biçimi#

POST /api/webhooks HTTP/1.1
Host: isbasi.apps.tecof.site
Content-Type: application/json
User-Agent: Tecof-Webhooks/1.0
X-Tecof-Event: order.paid
X-Tecof-Event-Id: evt_7f3a2c9e1b
X-Tecof-Delivery-Attempt: 1
X-Tecof-Merchant-Id: 66f0c0ffee0000000000abcd
X-Tecof-Installation-Id: 6720aa00bb11cc22dd33ee55
X-Tecof-App-Id: tcfa_xxxxxxxxxxxxxxxx
X-Tecof-Timestamp: 1760087770
X-Tecof-Signature: t=1760087770,v1=5f2c…e91a
X-Webhook-Event: order.paid

{
  "id": "evt_7f3a2c9e1b",
  "event": "order.paid",
  "test": false,
  "timestamp": "2026-10-10T09:16:10.000Z",
  "merchantId": "66f0c0ffee0000000000abcd",
  "installationId": "6720aa00bb11cc22dd33ee55",
  "data": {
    "orderId": "6720bb00cc11dd22ee33ff44",
    "orderNumber": "TCF-1001",
    "status": "confirmed",
    "paymentStatus": "paid",
    "totalPrice": 1050,
    "taxPrice": 175,
    "pricesIncludeTax": true,
    "currencyCode": "TRY",
    "customerEmail": "musteri@example.com",
    "merchantId": "66f0c0ffee0000000000abcd",
    "merchantName": "Örnek Mağaza"
  }
}

Mağaza olaylarının data alanı, mağaza webhook'larının gönderdiği yükün aynısıdır; Tecof merchantId ve merchantName alanlarını ekler. Sipariş olaylarında orderId, orderNumber, status, paymentStatus, totalPrice, taxPrice, pricesIncludeTax, currencyCode, customerEmail gibi özet alanlar gelir. Satırlar, adresler ve vergi kırılımı dahil siparişin tam ve kararlı şekli için GET /api/v1/orders/:id ile okuyun (api.orders.get(data.orderId)). Bkz. API ile Veri Erişimi.

Platform uygulamalarına ham sır içeren X-Webhook-Secret başlığı gönderilmez (yalnız eski birinci parti ve mağaza webhook'larında sürer). Doğrulama yalnız X-Tecof-Signature ile yapılır.

Yeniden Deneme ve Otomatik Pasifleştirme#

Teslimat geçmişinizi geliştirici API'sinden izleyebilirsiniz: GET /api/developer/apps/:id/deliveries.

Idempotency#

Aynı olay birden fazla kez gelebilir (yeniden deneme, ağ kopması). İşleyicinizi idempotent yazın:

1. Olay kimliği: X-Tecof-Event-Id (gövdede id) yeniden denemelerde aynıdır. İşlenen kimlikleri kendi deponuzda tutup tekrarı atlayın.
2. Kaynak durumu: Daha sağlam yol, işin yapılıp yapılmadığını kaynağın kendisinden anlamaktır. Örneğin fatura kesen bir uygulama faturayı oluşturunca siparişe invoiceNumber metafield'ı yazar; aynı sipariş için gelen ikinci order.paid bu metafield'ı görüp atlanır.
3. Sıra: Yeniden denemeler nedeniyle olaylar oluş sırasından farklı sırada gelebilir. Kararı olay yüküne değil, API'den okuduğunuz güncel duruma göre verin.

Örnek İşleyici (Next.js App Router)#

SDK'nın createWebhookHandler yardımcısı doğrulamayı, olay yönlendirmeyi ve yanıt kodlarını üstlenir. Dönen fonksiyon doğrudan bir Route Handler'dır:

// app/api/webhooks/route.ts
import { createWebhookHandler } from "@tecof/app-sdk";
import { tecof } from "@/lib/tecof";

export const POST = createWebhookHandler({
  app: tecof,
  handlers: {
    "app.installed": async (event) => {
      await tecof.client(event.installationId).settings.set({ invoiceMode: "draft" }, { merge: true });
    },

    "app.uninstalled": async (event) => {
      // Token'lar bu teslimat bittikten sonra iptal edilir; gerekirse burada API'yi çağırabilirsiniz.
      // Kendi sistemlerinizdeki kopyaları temizleyin (8 sn içinde).
    },

    "app.settings.updated": async (event) => {
      // Değerler gelmez; gerekirse api.settings.get() / api.secrets.get(key) ile okuyun
    },

    "order.paid": async (event) => {
      const api = tecof.client(event.installationId);
      const orderId = String(event.data.orderId);

      const existing = await api.metafields.list({ ownerType: "order", ownerId: orderId, namespace: "isbasi" });
      if (existing.some((m: { key: string }) => m.key === "invoiceNumber")) return; // zaten işlendi

      const order = await api.orders.get(orderId);
      // … faturayı oluştur, sonra siparişe invoiceNumber metafield'ı yaz
    },
  },
});

SDK yardımcısı olmadan#

// app/api/webhooks/route.ts
import { tecof } from "@/lib/tecof";

export async function POST(req: Request) {
  const rawBody = await req.text(); // ham gövde — imza bunun üzerinden hesaplanır

  let event;
  try {
    event = tecof.verifyWebhook(rawBody, req.headers); // Headers ya da düz nesne kabul eder
  } catch {
    return new Response("invalid signature", { status: 401 });
  }

  if (event.test) return new Response(null, { status: 204 });

  switch (event.event) {
    case "order.paid":
      // …
      break;
  }
  return new Response(null, { status: 204 });
}

İpuçları:

• İşleyiciyi 8 saniyelik zaman aşımının altında tutun ve işlem bitince 2xx dönün. 2xx dışındaki her yanıt yeniden denemeye ve ardışık hata sayacına yazılır.
• Kalıcı olarak işlenemeyecek bir olay için (ör. mağaza ayarları eksik) 2xx dönüp durumu kendi tarafınızda kaydedin; aksi hâlde yeniden denemeler ve ardışık hatalar aboneliği pasife düşürebilir.

Test Etme#

SECRET="$TECOF_CLIENT_SECRET"
T=$(date +%s)
BODY='{"id":"evt_local_1","event":"order.paid","test":false,"timestamp":"2026-10-10T09:16:10.000Z","merchantId":"66f0c0ffee0000000000abcd","installationId":"6720aa00bb11cc22dd33ee55","data":{"orderId":"6720bb00cc11dd22ee33ff44","orderNumber":"TCF-1001"}}'
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

curl -X POST http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Tecof-Event: order.paid" \
  -H "X-Tecof-Event-Id: evt_local_1" \
  -H "X-Tecof-Delivery-Attempt: 1" \
  -H "X-Tecof-Installation-Id: 6720aa00bb11cc22dd33ee55" \
  -H "X-Tecof-Timestamp: $T" \
  -H "X-Tecof-Signature: t=$T,v1=$SIG" \
  --data-binary "$BODY"

Elle imzalı istekte installationId gerçek bir test kurulumuna ait değilse API çağrıları (api.orders.get) başarısız olur; imza ve yönlendirme mantığını bu yolla, uçtan uca akışı test mağazasında tünelle doğrulayın.

Mağaza webhook’ları (panelden)#

Uygulama yazmadan, bir mağazanın olaylarını kendi sunucunuza göndermek için mağaza sahibi panelde (E-ticaret → Ayarlar → Webhook’lar) webhook tanımlayabilir. Bu webhook’lar aynı olay kataloğunu kullanır, * (tüm olaylar) jokerine izin verir ve eski usul X-Webhook-Secret başlığıyla doğrulanır. Panel aşağıdaki uçları JWT ile çağırır; üçüncü taraf entegrasyonlar için platform uygulaması önerilir.