Gamma ウェブフック & イベント

概要

Gamma のリアルタイム更新に対応したウェブフックハンドラーとイベント処理を実装します。

前提条件

• ウェブフック配信用の公開エンドポイント
• Gamma ダッシュボードからのウェブフックシークレット
• イベント駆動アーキテクチャの理解

手順

ステップ 1: ウェブフックエンドポイントの登録

// API 経由で登録
const webhook = await gamma.webhooks.create({
  url: 'https://your-app.com/webhooks/gamma',
  events: [
    'presentation.created',
    'presentation.updated',
    'presentation.exported',
    'presentation.deleted',
  ],
  secret: process.env.GAMMA_WEBHOOK_SECRET,
});

console.log('Webhook registered:', webhook.id);

ステップ 2: ウェブフックハンドラーの作成

// routes/webhooks/gamma.ts
import express from 'express';
import crypto from 'crypto';

const router = express.Router();

// ウェブフック署名の検証
function verifySignature(payload: string, signature: string): boolean {
  const secret = process.env.GAMMA_WEBHOOK_SECRET!;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

router.post('/gamma',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-gamma-signature'] as string;
    const payload = req.body.toString();

    // 署名を検証
    if (!verifySignature(payload, signature)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // イベントを解析
    const event = JSON.parse(payload);

    // 受信確認を素早く返す
    res.status(200).json({ received: true });

    // イベントを非同期で処理
    await processEvent(event);
  }
);

export default router;

ステップ 3: イベント処理

// services/gamma-events.ts
interface GammaEvent {
  id: string;
  type: string;
  data: any;
  timestamp: string;
}

type EventHandler = (data: any) => Promise<void>;

const handlers: Record<string, EventHandler> = {
  'presentation.created': async (data) => {
    console.log('New presentation:', data.id);
    await notifyTeam(`New presentation created: ${data.title}`);
    await updateDatabase({ presentationId: data.id, status: 'created' });
  },

  'presentation.updated': async (data) => {
    console.log('Presentation updated:', data.id);
    await updateDatabase({ presentationId: data.id, status: 'updated' });
  },

  'presentation.exported': async (data) => {
    console.log('Export complete:', data.exportUrl);
    await sendExportNotification(data.userId, data.exportUrl);
  },

  'presentation.deleted': async (data) => {
    console.log('Presentation deleted:', data.id);
    await cleanupAssets(data.id);
  },
};

export async function processEvent(event: GammaEvent) {
  const handler = handlers[event.type];

  if (!handler) {
    console.warn('Unhandled event type:', event.type);
    return;
  }

  try {
    await handler(event.data);
    await recordEventProcessed(event.id);
  } catch (err) {
    console.error('Event processing failed:', err);
    await recordEventFailed(event.id, err);
  }
}

ステップ 4: 信頼性向上のためのイベントキュー

// services/event-queue.ts
import Bull from 'bull';

const eventQueue = new Bull('gamma-events', {
  redis: process.env.REDIS_URL,
});

// 直接処理ではなくキューに追加
export async function queueEvent(event: GammaEvent) {
  await eventQueue.add(event, {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 5000,
    },
  });
}

// キューを処理
eventQueue.process(async (job) => {
  await processEvent(job.data);
});

eventQueue.on('failed', (job, err) => {
  console.error(`Event ${job.id} failed:`, err.message);
  // デッドレターキューに送信またはアラート
});

ステップ 5: ウェブフック管理

// ウェブフックを一覧表示
const webhooks = await gamma.webhooks.list();

// ウェブフックを更新
await gamma.webhooks.update(webhookId, {
  events: ['presentation.created', 'presentation.exported'],
});

// ウェブフックを削除
await gamma.webhooks.delete(webhookId);

// ウェブフックをテスト
await gamma.webhooks.test(webhookId);

イベントタイプリファレンス

イベント	説明	ペイロード
presentation.created	新規プレゼンテーション	id, title, userId
presentation.updated	スライド修正	id, changes[]
presentation.exported	エクスポート完了	id, format, url
presentation.deleted	プレゼンテーション削除	id
presentation.shared	共有設定更新	id, shareSettings

出力

• 検証済みウェブフックハンドラー
• イベント処理パイプライン
• 信頼性の高いキューシステム
• ウェブフック管理 API

エラーハンドリング

エラー	原因	解決方法
無効な署名	シークレット不一致	ウェブフックシークレットを確認
タイムアウト	処理が遅い	非同期キューを使用
重複イベント	再配信時の重複	べき等性を実装
イベント欠落	エンドポイント停止	信頼性の高いホスティングを使用

リソース

• Gamma ウェブフックガイド
• ウェブフックベストプラクティス

次のステップ

最適化については gamma-performance-tuning に進んでください。