Moonborn — Developers

Webhook olay kataloğu

Moonborn'un yaydığı 16 webhook olay tipi — persona yaşam döngüsü, üretim hattı, faturalama, pazaryeri, moderasyon, sistem ping'i.

Her Moonborn webhook gönderimi aşağıdaki tiplerden birinin olayını taşır. 16 gerçek olay tipi — kaynak kodda WEBHOOK_EVENT_TYPES olarak tanımlıdır; bu sayfa insan-okunabilir görünümdür.

Bu sayfayı bitirdiğinde

16 olay tipinin kategorilerini ayırt edebileceksin.
Her olayın ne zaman tetiklendiğini bileceksin.
persona.audit_failed'ın birden çok-anlama-gelen (overloaded) davranışını (drift veya denetim sebebi) doğru ele alabileceksin.
Zarf şeklini ve idempotent işleme için id alanını kullanabileceksin.
Webhook ile gönderilmeyen şeyleri (akış — streaming, mesaj-başı) ayırt edebileceksin.

Ön koşul: Webhook'lar entegrasyon kurulumu.

Persona yaşam döngüsü (6)

Tip	Ne zaman tetiklenir
`persona.created`	Yeni persona üretim hattı bitti
`persona.updated`	Persona üstverisi değişti (slug, görünürlük, vb.)
`persona.deleted`	Yumuşak silme; 30 günlük geçiş süresi başlar
`persona.archived`	Persona arşivlendi (lineage korundu, çalışma zamanı kapalı)
`persona.regenerated`	Hat seçili adımdan yeniden koştu
`persona.audit_failed`	Denetim eşik altı veya drift uyarısı veya test takımı başarısız — `data.reason` ayırt eder

Üretim hattı (3)

Tip	Ne zaman
`generation.run.started`	Hat koşumu başladı
`generation.run.completed`	Hat koşumu başarıyla bitti
`generation.run.failed`	Hat sonlu başarısızlık (3 yeniden denemenin ardından)

Her persona üretimi / refine / fork'unda tetiklenir. Hat gözlemlenebilirliği (observability) izliyorsan abone ol; normal yaşam döngüsü için persona.* olayları genelde yeter.

Abonelik / faturalama (3)

Tip	Ne zaman
`subscription.upgraded`	Plan bir kademe yukarı (örn. Pro → Team)
`subscription.downgraded`	Plan bir kademe aşağı
`subscription.cancelled`	Abonelik iptal edildi (faturalama dönemi sonunda etkin)

Kullanım: CRM (HubSpot) senkronizasyonu, finans uyarısı, karşılama e-postası gönderme.

Pazaryeri (2)

Tip	Ne zaman
`marketplace.persona.published`	Yayın moderasyondan geçti, herkese açık
`marketplace.persona.purchased`	Ücretli yayın satın alındı (Enterprise ticareti)

Moderasyon (1)

Tip	Ne zaman
`moderation.flagged`	Moderasyon aşamalarından biri `pass` (geçti) olmayan karar üretti

Yük data.stage alanı (input / output / impersonation / pii) hangi aşamanın işaret attığını gösterir. Detay: Moderasyon hattı.

Sistem (1)

Tip	Ne zaman
`webhook.endpoint.test_ping`	`POST /v1/webhooks/{id}/ping` ile elle test

Bağlantı testleri içindir. Alıcının 200 OK döndürmesi sağlık kontrolüdür.

Joker (wildcard) abonelik

await client.webhooks.create({
  url: '...',
  events: ['*'],  // hepsine abone
});

Üretim işleyicileri için tavsiye edilmez — 16+ tip üzerinde if/else yazmak gerekir. Denetim kaydı arşivleme veya jenerik olay akışı için yararlıdır.

Zarf şekli

Tüm olaylar aynı zarfta gelir:

{
  "id": "evt_01H...",
  "type": "persona.audit_failed",
  "occurredAt": "2026-05-17T12:00:00Z",
  "orgId": "org_...",
  "workspaceId": "ws_...",
  "data": { /* tipe özgü */ }
}

Alan	Anlamı
`id`	Benzersiz, idempotent. Yeniden deneme / yeniden gönderim için tekrar tespit (dedupe) anahtarı olarak kullan.
`type`	Olay tipi (16'dan biri)
`occurredAt`	Olayın tetiklendiği zaman (ISO 8601)
`orgId` / `workspaceId`	Çok kiracılı (multi-tenant) yönlendirme için
`data`	Tipe özgü yük (her tip için ayrı şema)

İdempotent işleme — tekrar tespit deseni

Webhook yeniden deneme + yeniden gönderim, yinelenen gönderim üretir; işleyicin idempotent olmalı:

async function handleEvent(event: WebhookEvent) {
  // Tekrar tespit: event.id'yi önbelleğe al
  const seen = await redis.set(`webhook:${event.id}`, '1', {
    NX: true,
    EX: 86400, // 24 saat
  });
  if (!seen) return; // Daha önce işlendi, atla
 
  switch (event.type) {
    case 'persona.audit_failed':
      await handleAuditFailed(event.data);
      break;
    // ...
  }
}

Gönderim anlambilimi

HMAC-SHA256 imzası — X-Moonborn-Signature başlığı (detay: Webhook imza doğrulama)
5 yeniden deneme üstel geri çekilmeyle (1dk → 2dk → 5dk → 30dk → 2sa)
5 başarısızlık sonrası dead-letter (ölü mektup) kuyruğu; panelden veya POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay ile yeniden gönderim