Webhooks

SparkSheetsのイベントをリアルタイムで外部サービスに通知します。シート作成、Spark実行、セッション保存などのイベントを即座にキャッチできます。

概要

Webhooksは、SparkSheetsで発生したイベントをあなたのサーバーにHTTP POSTで通知する仕組みです。ポーリングなしでリアルタイムにデータ変更を検知できます。

Webhooksを使用するにはProプラン以上が必要です。料金プランをご確認ください。

Webhooksでできること

  • シート作成・更新・削除を外部DBに同期
  • Spark実行結果をSlackやDiscordに通知
  • セッション保存をトリガーにバックアップ処理
  • ナレッジ追加をチーム全体に通知
  • Zapier、n8n、Make等との連携

セットアップ

Webhooksは管理画面またはAPIから設定できます。

1

エンドポイントURLを準備

Webhookを受信するサーバーのURLを用意します。HTTPS必須です。

2

Webhookを登録

管理画面の「設定 > Webhooks」から、またはAPIで登録します。

3

イベントを選択

通知を受け取りたいイベントを選択します。「*」で全イベントを受信できます。

4

シークレットを保存

生成されたWebhookシークレットを安全に保存してください。署名検証に使用します。

APIでの登録

# Webhook登録
curl -X POST https://sparksheets.ai/api/v1/webhooks \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["sheet.created", "sheet.updated", "spark.executed"]
  }'

レスポンス例

{
  "success": true,
  "webhook": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook",
    "events": ["sheet.created", "sheet.updated", "spark.executed"],
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

イベント一覧

以下のイベントでWebhook通知が発生します。

sheet.created

新しいシートが作成されたときに発火します。

{
  "event": "sheet.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "sheet_id": "sheet_abc123",
    "name": "プロジェクト計画書",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

sheet.updated

シートの内容が更新されたときに発火します。

{
  "event": "sheet.updated",
  "timestamp": "2025-01-15T10:35:00Z",
  "data": {
    "sheet_id": "sheet_abc123",
    "changes": ["content", "title"],
    "updated_at": "2025-01-15T10:35:00Z"
  }
}

sheet.deleted

シートが削除されたときに発火します。

{
  "event": "sheet.deleted",
  "timestamp": "2025-01-15T10:40:00Z",
  "data": {
    "sheet_id": "sheet_abc123",
    "deleted_at": "2025-01-15T10:40:00Z"
  }
}

spark.executed

SparkまたはAI機能が実行されたときに発火します。

{
  "event": "spark.executed",
  "timestamp": "2025-01-15T10:32:00Z",
  "data": {
    "spark_id": "spark_xyz789",
    "spark_name": "文章校正",
    "sheet_id": "sheet_abc123",
    "executed_at": "2025-01-15T10:32:00Z"
  }
}

session.saved

Claude Codeセッションが保存されたときに発火します。

{
  "event": "session.saved",
  "timestamp": "2025-01-15T18:00:00Z",
  "data": {
    "session_id": "sess_def456",
    "title": "API実装セッション"
  }
}

session.handover

引き継ぎシートが作成されたときに発火します。

{
  "event": "session.handover",
  "timestamp": "2025-01-15T18:30:00Z",
  "data": {
    "session_id": "sess_def456",
    "handover_id": "ho_ghi789"
  }
}

knowledge.saved

解決策やスニペットがナレッジベースに保存されたときに発火します。

{
  "event": "knowledge.saved",
  "timestamp": "2025-01-15T14:20:00Z",
  "data": {
    "type": "solution",
    "id": "sol_jkl012",
    "title": "CORS エラーの解決方法"
  }
}

export.completed

エクスポート処理が完了したときに発火します。

{
  "event": "export.completed",
  "timestamp": "2025-01-15T11:00:00Z",
  "data": {
    "sheet_id": "sheet_abc123",
    "format": "pdf",
    "url": "https://sparksheets.ai/exports/xxx.pdf"
  }
}

署名検証

セキュリティ上の重要事項

Webhookリクエストが本当にSparkSheetsから送信されたものか確認するため、必ず署名を検証してください。署名検証を行わないと、悪意のある第三者からの偽のリクエストを受け入れてしまう可能性があります。

署名の仕組み

SparkSheetsは各Webhookリクエストに X-SparkSheets-Signature ヘッダーを付与します。この署名は、リクエストボディとWebhookシークレットを使ってHMAC SHA-256で計算されます。

PHPでの検証例

<?php
// リクエストボディを取得
$payload = file_get_contents('php://input');

// 署名ヘッダーを取得
$signature = $_SERVER['HTTP_X_SPARKSHEETS_SIGNATURE'] ?? '';

// 期待される署名を計算
$secret = 'whsec_your_webhook_secret';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

// 署名を検証(タイミング攻撃対策)
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// 検証成功 - ペイロードを処理
$data = json_decode($payload, true);
// ... 処理を続行

Node.jsでの検証例

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

// Express.js での使用例
app.post('/webhook', (req, res) => {
    const signature = req.headers['x-sparksheets-signature'];
    const payload = JSON.stringify(req.body);

    if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }

    // 検証成功 - 処理を続行
    console.log('Webhook received:', req.body);
    res.status(200).json({ received: true });
});

リトライポリシー

Webhookの配信に失敗した場合、SparkSheetsは自動的にリトライを行います。

リトライ回数 待機時間 累計経過時間
1回目 1分後 1分
2回目 5分後 6分
3回目 30分後 36分
4回目 2時間後 2時間36分
5回目(最終) 24時間後 約25時間

成功とみなされる条件

  • HTTPステータスコード 2xx(200-299)を返す
  • 5秒以内にレスポンスを返す

失敗とみなされる条件

  • HTTPステータスコード 4xx または 5xx
  • 5秒以上のタイムアウト
  • 接続エラー(DNS解決失敗、接続拒否など)

5回のリトライがすべて失敗した場合、Webhookは無効化されます。管理画面から再度有効化できます。

実装例

Slackへの通知

シート作成時にSlackチャンネルに通知する例です。

<?php
// SparkSheetsからのWebhookを受信
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// sheet.created イベントのみ処理
if ($data['event'] === 'sheet.created') {
    $sheetName = $data['data']['name'];

    // Slack Webhook URL
    $slackUrl = 'https://hooks.slack.com/services/xxx/yyy/zzz';

    // メッセージを送信
    $message = [
        'text' => "新しいシート「{$sheetName}」が作成されました",
        'icon_emoji' => ':sparkles:'
    ];

    $ch = curl_init($slackUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($message));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_exec($ch);
    curl_close($ch);
}

http_response_code(200);
echo json_encode(['received' => true]);

外部DBへの同期

シート更新時にMySQLデータベースと同期する例です。

<?php
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

if ($data['event'] === 'sheet.updated') {
    $sheetId = $data['data']['sheet_id'];
    $updatedAt = $data['data']['updated_at'];

    // PDOでデータベース更新
    $pdo = new PDO('mysql:host=localhost;dbname=myapp', 'user', 'pass');

    $stmt = $pdo->prepare('
        UPDATE sheets
        SET synced_at = ?, needs_sync = 1
        WHERE external_id = ?
    ');

    $stmt->execute([$updatedAt, $sheetId]);
}

http_response_code(200);

活用事例

Slack/Discord通知

チームメンバーがシートを作成・更新したときにチャンネルに通知。作業の可視化に。

データ同期

SparkSheetsのシートデータを外部データベースやCRMにリアルタイム同期。

バックアップ

シート更新のたびにS3やGoogle Cloud Storageにバックアップを自動作成。

自動化ワークフロー

Zapier、n8n、Makeと連携して、SparkSheetsのイベントをトリガーに複雑なワークフローを実行。

分析・レポート

Spark実行回数やシート作成頻度を集計し、チームの生産性を可視化。

アラート

特定の条件(大量更新、重要シートの削除など)でアラートを発報。

パスワードを忘れた
または
または

パスワードリセット

登録したメールアドレスにリセットリンクを送信します