Moonborn — Developers

Webhook-Events

Der volle Katalog von Webhook-Event-Typen, die Moonborn emittiert. Sechzehn echte Events, die Persona-Lifecycle, Generation, Billing, Marketplace, Moderation und System-Test-Pings abdecken.

Jede Moonborn-Webhook-Delivery trägt ein Event eines der folgenden Typen. Die volle Liste lebt im Source als WEBHOOK_EVENT_TYPES; diese Seite ist die human-readable View.

Persona-Lifecycle (6)

Typ	Wann
`persona.created`	Eine neue Persona beendete die Generation-Pipeline.
`persona.updated`	Veränderliches Metadata einer Persona änderte sich (Slug, Visibility etc.).
`persona.deleted`	Persona soft-deleted (tritt 30-Day-Grace an).
`persona.archived`	Persona archiviert (read-only; Lineage bewahrt).
`persona.regenerated`	Pipeline lief von einem gewählten Step erneut.
`persona.audit_failed`	Audit-Verdict fiel unter Schwelle, ODER Drift-Detection alertete auf eine Chat-Antwort.

persona.audit_failed ist überladen — data.reason trägt entweder audit_below_threshold, provocation_test_failed oder voice_drift. Inspiziere das Reason-Feld; das Schema ist sonst gleich.

Generation-Pipeline (3)

Typ	Wann
`generation.run.started`	Pipeline-Run hat angefangen.
`generation.run.completed`	Pipeline-Run erfolgreich beendet.
`generation.run.failed`	Pipeline-Run terminal gefailt (nach Retries).

Diese feuern auf jeder Persona-Generation, Refine, Fork. Abonniere sie nur, wenn du Pipeline-Observability trackst — für normalen Persona-Lifecycle reichen die persona.*-Events meist.

Subscription / Billing (3)

Typ	Wann
`subscription.upgraded`	Plan ein Tier nach oben verschoben (z. B. Pro → Team).
`subscription.downgraded`	Plan ein Tier nach unten verschoben.
`subscription.cancelled`	Subscription gekündigt (wirksam Ende der Periode).

Marketplace (2)

Typ	Wann
`marketplace.persona.published`	Listing passierte Moderation; öffentlich sichtbar.
`marketplace.persona.purchased`	Bezahltes Listing gekauft (Enterprise-Commerce).

Moderation (1)

Typ	Wann
`moderation.flagged`	Eine Moderation-Stage produzierte ein non-`pass`-Verdict (Input-Intent, Output-Content, Impersonation, PII).

System (1)

Typ	Wann
`webhook.endpoint.test_ping`	Gefeuert von `POST /v1/webhooks/{id}/ping` für Connectivity-Tests.

Abonniere mit events: ['*'], um jeden Event-Typ zu empfangen. Nützlich für Audit-Log-Archivierung oder generic Event-Streaming; nicht empfohlen für Production-Handler (du machst if/else über 16+ Typen).

Envelope-Form

Jedes Event versendet im selben Envelope:

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

id ist unique + idempotent — nutze es als deinen Dedupe-Key bei Retries.

Delivery-Semantik

HMAC-SHA256-signiert (X-Moonborn-Signature-Header).
Fünf Retries mit Exponential Backoff (1m → 2m → 5m → 30m → 2h).
Dead-Letter nach fünf Failures; replay-bar aus Dashboard oder POST /v1/webhooks/{id}/deliveries/{id}/replay.

Siehe die Webhooks-Integration für Setup + den Webhook signature verification guide für Production-Receiver.

Ehrlicher Scope

Sechzehn Event-Typen. Mehr nicht. Wir emittieren nicht:

Per-Message-Chat-Events (zu hochvolumig; nutze stattdessen SSE- Streaming am Chat-Endpoint).
Per-Step-Pipeline-Events (nutze SSE auf POST /v1/personas?stream=true).
User-Action-Events (heute keine member.invited-style Events).

Wenn du einen Typ brauchst, der nicht hier ist, ist der Audit-Log der breitere Record. Webhooks emittieren das Edge-Triggered-Subset, das es wert ist, gepusht zu werden.