Webhook’lar (Giden)

HummyTummy, tenant’ınızda bir olay olduğunda kayıtlı uç noktanıza HMAC-SHA256 imzalı bir HTTP POST atar. Böylece sipariş, ödeme ve ürün/yenileme olaylarına anlık tepki verebilir; yoklamaya (polling) ihtiyaç duymazsınız.

Tüm yollar /api global ön eki altındadır.

Abone olun

Bir abonelik oluşturun. secret yalnızca bir kez döner — onu güvenli biçimde saklayın; bir daha gösterilmez ve geri türetilemez.

curl -X POST https://hummytummy.com/api/v1/webhooks/subscriptions \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.ornek.com/hummytummy",
    "events": ["order.created.v1", "payment.succeeded.v1"]
  }'

const res = await fetch(
  "https://hummytummy.com/api/v1/webhooks/subscriptions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${adminJwt}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://hooks.ornek.com/hummytummy",
      events: ["order.created.v1", "payment.succeeded.v1"],
    }),
  },
);
const { secret } = await res.json(); // SADECE bir kez döner — güvenli sakla

İstek gövdesi:

Yanıt (özet):

{
  "id": "0190a1b2-...",
  "tenantId": "...",
  "url": "https://hooks.ornek.com/hummytummy",
  "events": ["order.created.v1", "payment.succeeded.v1"],
  "status": "active",
  "secret": "whs_AbCdEf..."
}

Abonelikleri listeleyin / iptal edin:

GET    /api/v1/webhooks/subscriptions
DELETE /api/v1/webhooks/subscriptions/:id

Teslim edilen yük (payload)

Her teslim, JSON gövdesiyle bir POST’tur:

{
  "id": "0190a1b2-c3d4-...",
  "type": "order.created.v1",
  "tenantId": "...",
  "payload": { "...olaya-özgü alanlar..." }
}

Ayrıca şu başlıklar gelir:

İmza doğrulama

İmza, gövde üzerinden hesaplanan zaman damgalı bir HMAC-SHA256’dır:

X-HummyTummy-Signature: t=<unix-ms>,v1=<hmac-sha256-hex>

İmza şu şekilde üretilir — imzalanan metin "<timestamp>.<rawBody>"’dir, anahtar ise sizin secret’ınız:

v1 = HMAC_SHA256(secret, `${t}.${rawBody}`)  // hex

Doğrulama adımları (HummyTummy’nin verify mantığıyla birebir aynı):

Node.js (Express) doğrulama örneği

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
 
const app = express();
 
// Ham gövdeyi sakla — imza ham byte'lar üzerinden hesaplanır.
app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf; } }));
 
function verify(
  secret: string,
  header: string,
  rawBody: string,
  toleranceMs = 5 * 60_000,
): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const ts = Number(parts.t);
  const v1 = String(parts.v1 ?? "");
  if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > toleranceMs) return false;
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  if (expected.length !== v1.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
 
app.post("/hummytummy", (req, res) => {
  const sig = req.header("X-HummyTummy-Signature") ?? "";
  const raw = (req as any).rawBody.toString("utf8");
  if (!verify(process.env.WEBHOOK_SECRET!, sig, raw)) {
    return res.sendStatus(401); // imza geçersiz/eski
  }
  // İdempotency: aynı X-HummyTummy-Event-Id'yi iki kez işleme.
  const eventId = req.header("X-HummyTummy-Event-Id");
  // ... olayı işle ...
  res.sendStatus(200); // 2xx = başarılı teslim
});

Olay tipleri

events alanında belirli tipleri listeleyin ya da "*" ile tüm yayınlanabilir olayları yakalayın. Tipler <alan>.<eylem>.v<sürüm> biçimindedir.

Örnek yayınlanabilir tipler:

Engelli (BLOCKED) olaylar

Bazı hassas olaylar dahili tutulur ve hiçbir koşulda dışarı verilmez — "*" aboneliği bile bunları almaz. Engelleme ön ek bazlıdır; aşağıdaki ön ekle başlayan hiçbir olay teslim edilmez:

user.password
user.email_verification
auth.
subscription.upgrade.requested
subscription.renewal.failed
subscription.payment.
kms.
audit.

Yeniden deneme ve otomatik duraklatma

Teslim, her 30 saniyede bir çalışan bir worker tarafından yapılır.

• Zaman aşımı: tek teslim 15 saniyeyle sınırlıdır.
• Yeniden deneme: 2xx dışı yanıt veya ağ hatasında artan beklemelerle (30 sn, 2 dk, 10 dk, 1 saat, 6 saat) en fazla 5 deneme; ardından teslim failed işaretlenir.
• Otomatik duraklatma: bir abonelik 20 ardışık başarısızlıktan sonra otomatik paused’a alınır. Ölü bir uç noktanın worker’ı tüketmesini engeller; yeniden çalışır hale getirip yeni bir abonelik oluşturmanız gerekir.
• Başarı sayacı sıfırlama: başarılı bir teslim ardışık-başarısızlık sayacını 0’a çeker.

SSRF koruması (allowlist)

Webhook URL’leri hem abone olurken hem de her teslimden hemen önce bir güvenlik kapısından geçer. Bu, tenant’ın iç servislere ya da bulut metadata uç noktalarına (örn. 169.254.169.254) self-fetch yapmasını engeller.

Engellenenler:

• Genel (public) olmayan IP’ler: loopback, özel/dahili aralıklar, link-local, cloud metadata adresleri ve bunların IPv4-mapped IPv6 karşılıkları.
• Tehlikeli portlar (Redis, Postgres, vb.).
• URL içinde userinfo (user:pass@host).
• http/https dışı protokoller.

En iyi pratikler

• İmzayı her zaman doğrulayın ve id üzerinden dedup yapın.
• Hızlıca 2xx dönün; ağır işi kuyruğa alın (15 sn timeout’u aşmayın).
• secret’ı sunucu tarafında, ortam değişkeninde/kasada saklayın.
• Bir aboneliği duraklatıldı bulursanız uç noktanızı onarın ve yeniden abone olun.
• Mümkünse HTTPS uç noktası kullanın.