Moonborn — Developers

Webhook event'leri

Moonborn'un yaydığı webhook event tiplerinin tam kataloğu. Persona yaşam döngüsü, generation, billing, marketplace, moderation ve sistem test ping'lerini kapsayan on altı gerçek event.

Her Moonborn webhook delivery'si aşağıdaki tiplerden birinin event'ini taşır. Tam liste kaynak kodda WEBHOOK_EVENT_TYPES olarak yaşar; bu sayfa human-readable view.

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

Tip	Ne zaman
`persona.created`	Yeni bir persona generation pipeline'ı bitirdi.
`persona.updated`	Bir personanın değiştirilebilir metadata'sı değişti (slug, visibility vb.).
`persona.deleted`	Persona soft-delete'lendi (30-day grace'e girer).
`persona.archived`	Persona arşivlendi (read-only; lineage korundu).
`persona.regenerated`	Pipeline seçili bir adımdan yeniden çalıştı.
`persona.audit_failed`	Audit verdict'i eşik altına düştü, YA DA drift detection bir chat yanıtında alert verdi.

persona.audit_failed overloaded — data.reason ya audit_below_threshold, provocation_test_failed ya da voice_drift taşır. Reason alanını incele; şema aksi halde aynı.

Generation pipeline (3)

Tip	Ne zaman
`generation.run.started`	Pipeline run başladı.
`generation.run.completed`	Pipeline run başarıyla bitti.
`generation.run.failed`	Pipeline run terminal başarısız oldu (retry sonrası).

Bunlar her persona generation, refine, fork'ta tetiklenir. Pipeline observability izliyorsan abone ol — normal persona yaşam döngüsü için persona.* event'leri genelde yeter.

Subscription / billing (3)

Tip	Ne zaman
`subscription.upgraded`	Plan bir tier yukarı taşındı (örn. Pro → Team).
`subscription.downgraded`	Plan bir tier aşağı taşındı.
`subscription.cancelled`	Subscription iptal edildi (period sonunda etkin).

Marketplace (2)

Tip	Ne zaman
`marketplace.persona.published`	Listing moderasyondan geçti; publicly visible.
`marketplace.persona.purchased`	Ücretli listing satın alındı (Enterprise commerce).

Moderation (1)

Tip	Ne zaman
`moderation.flagged`	Herhangi bir moderasyon stage non-`pass` verdict üretti (input intent, output content, impersonation, PII).

Sistem (1)

Tip	Ne zaman
`webhook.endpoint.test_ping`	Connectivity testleri için `POST /v1/webhooks/{id}/ping` tarafından tetiklenir.

Her event tipini almak için events: ['*'] ile abone ol. Audit-log arşivleme ya da generic event streaming için yararlı; production handler'lar için tavsiye edilmez (16+ tip üzerinde if/else yapacaksın).

Envelope şekli

Her event aynı envelope'da gönderilir:

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

id unique + idempotent — retry'larda dedupe key'in olarak kullan.

Delivery semantiği

HMAC-SHA256 imzalı (X-Moonborn-Signature header).
Exponential backoff ile beş retry (1dk → 2dk → 5dk → 30dk → 2sa).
Beş başarısızlık sonrası dead-letter; dashboard'dan ya da POST /v1/webhooks/{id}/deliveries/{id}/replay'den replay'lenebilir.

Kurulum için Webhooks integration'a ve production receiver'ları için Webhook signature verification guide'a bak.

Dürüst kapsam

On altı event tipi. Daha fazla değil. Yaymıyoruz:

Mesaj başı chat event'leri (çok yüksek hacim; chat endpoint'inde SSE streaming kullan).
Step başı pipeline event'leri (POST /v1/personas?stream=true'da SSE kullan).
User-action event'leri (bugün member.invited-stili event yok).

Burada olmayan bir tipe ihtiyacın varsa, audit log daha geniş kayıt. Webhook'lar push edilmeye değer edge-triggered alt kümeyi yayar.