Webhooks

Webhooks sind, wie Moonborn Runtime-Events in deinen Stack pusht — Persona-Lifecycle, Generation-Pipeline-Outcomes, Billing-Änderungen, Moderation-Flags. Heute werden sechzehn echte Event-Typen versendet (siehe Webhook events reference).

Abonnieren

const hook = await client.webhooks.createWebhook({
  url: 'https://your-app.com/webhooks/moonborn',
  events: ['persona.created', 'persona.audit_failed'],
  description: 'Production listener',
});
 
console.log(hook.signingSecret);
// ⚠ Genau einmal zurückgegeben. Speichere ihn; nie wieder lesbar.

Verwende events: ['*'], um alle Events zu abonnieren. Pro-Event- Listen halten deine Handler enger.

Verifizieren

Jede Delivery trägt einen X-Moonborn-Signature-Header:

X-Moonborn-Signature: t=1747497600,v1=2c4f8...

Das t ist der Unix-Timestamp; v1 ist das HMAC-SHA256 von {t}.{rawBody}, gekeyt mit dem Signing-Secret.

import crypto from 'node:crypto';
 
function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=')),
  );
  const t = parts['t'];
  const v1 = parts['v1'];
  const signed = `${t}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signed)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(v1 ?? '', 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

Lehne Deliveries älter als 5 Minuten (t-Timestamp) ab, um Replay- Attacks zu verhindern. Siehe den Webhook signature verification guide für Production-grade Varianten.

Retry-Policy

Nach fünf Failures geht die Delivery in die Dead-Letter-Queue. Der Endpoint bleibt aktiv; nachfolgende Events versuchen weiter Delivery.

Konfigurierbar in api.webhooks.retry.* (Org-Scope, Enterprise kann den Schedule tunen).

Replay

Failed Deliveries sind replay-bar:

const failed = await client.webhooks.listDeliveries({
  webhookId: hook.id,
  status: 'failed',
});
 
for (const d of failed) {
  await client.webhooks.replayDelivery({
    webhookId: hook.id,
    deliveryId: d.id,
  });
}

Replays bewahren den Original-Payload + Signature-Timestamp. Dein Handler muss sie als idempotent behandeln; nutze das id-Feld des Event-Payloads als deinen Dedupe-Key.

Test-Deliveries

POST /v1/webhooks/{id}/ping feuert ein synthetisches webhook.endpoint.test_ping-Event, sodass du den Receiver verifizieren kannst, ohne auf ein echtes Event zu warten.

Den Secret rotieren

await client.webhooks.rotateSecret({ id: hook.id });

Gibt einen neuen Signing-Secret zurück. Der alte bleibt für die konfigurierte Grace-Period gültig (api.webhooks.secret_rotation_grace_minutes, Standard 60). Update deinen Receiver, dann lass den alten Secret ablaufen.

Tarif

Team und höher.

Ehrlicher Scope

Webhooks liefern Events. Sie sind keine Streaming-API für Echtzeit-Chat oder Generation-Progress — das ist SSE auf den Chat-/ Personas-Endpoints. Nutze Webhooks für Edge-Triggered- Benachrichtigungen (etwas ist passiert, handle), nicht für das Tailen eines Streams.

Weiter

• Drift-spezifisches Abo: Handle voice drift tutorial.
• Signature-Verification-Deep-Dive: Webhook signature verification guide.
• Volle Event-Liste: Webhook events reference.
• Webhooks API reference.