Webhooks

Webhook'lar Moonborn'un runtime event'lerini stack'ine push ettiği yol — persona yaşam döngüsü, generation pipeline sonuçları, billing değişiklikleri, moderation flag'leri. Bugün on altı gerçek event tipi gönderilir (bkz. Webhook events reference).

Abone ol

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);
// ⚠ Tam olarak bir kez döner. Sakla; bir daha okunamaz.

Tüm event'lere abone olmak için events: ['*'] kullan. Event başı listeler handler'larını daha sıkı tutar.

Doğrula

Her delivery bir X-Moonborn-Signature header'ı taşır:

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

t Unix timestamp; v1 signing secret ile anahtarlanmış {t}.{rawBody}'nin HMAC-SHA256'sı.

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'),
  );
}

Replay attack'leri önlemek için 5 dakikadan eski delivery'leri reddet (t timestamp). Production-grade varyantlar için Webhook signature verification guide'a bak.

Retry policy

Beş başarısızlık sonrası delivery dead-letter queue'ya gider. Endpoint aktif kalır; sonraki event'ler hâlâ delivery dener.

api.webhooks.retry.* üzerinden konfigüre edilebilir (org scope, Enterprise schedule'ı tune edebilir).

Replay

Başarısız delivery'ler replay'lenebilir:

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,
  });
}

Replay'ler orijinal payload + signature timestamp'ı korur. Handler'ın bunları idempotent kabul etmeli; dedupe key'in olarak event payload'unun id alanını kullan.

Test delivery'leri

POST /v1/webhooks/{id}/ping sentetik bir webhook.endpoint.test_ping event'i tetikler — gerçek bir event beklemeden receiver'ı doğrulayabilirsin.

Secret'ı rotate et

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

Yeni bir signing secret döner. Eskisi konfigüre edilmiş grace period süresince geçerli kalır (api.webhooks.secret_rotation_grace_minutes, default 60). Receiver'ını güncelle, sonra eskiyi expire et.

Tarif

Team ve üstü.

Dürüst kapsam

Webhook'lar event delivery eder. Real-time chat ya da generation ilerlemesi için bir streaming API değil — o, chat / personas endpoint'lerinde SSE. Webhook'ları edge-triggered bildirimler için kullan (bir şey oldu, aksiyon al), bir stream'i tailing için değil.

Sonraki

• Drift-spesifik abonelik: Handle voice drift tutorial.
• Signature verification derin dalış: Webhook signature verification guide.
• Tam event listesi: Webhook events reference.
• Webhooks API reference.