Webhook

Slack、Discord、またはカスタム Webhook を通じて、予算アラート、プロバイダーステータス変更、日次サマリーのリアルタイム通知を受信します。

機能

複数のフォーマット — Slack、Discord、または汎用JSON
イベントフィルタリング — 特定のイベントタイプを購読
カスタムヘッダー — 認証またはカスタムヘッダーを追加
非同期配信 — ノンブロッキングな Webhook 配信
自動フォーマット — 絵文字と色を使用したリッチメッセージ
テスト機能 — 有効化前に Webhook 設定を検証

設定

{
  "webhooks": [
    {
      "enabled": true,
      "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
      "events": [
        "budget_warning",
        "budget_exceeded",
        "provider_down",
        "provider_up",
        "failover",
        "daily_summary"
      ],
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  ]
}

イベントタイプ

イベント	説明	トリガー時
`budget_warning`	予算閾値に到達	支出が制限の80%に達した時
`budget_exceeded`	予算制限を超過	支出が設定された制限を超えた時
`provider_down`	プロバイダーが不健全になった	成功率が70%を下回った時
`provider_up`	プロバイダーが回復	不健全なプロバイダーが再び健全になった時
`failover`	リクエストがフェイルオーバー	リクエストがバックアッププロバイダーに切り替わった時
`daily_summary`	日次使用状況サマリー	毎日UTC午前0時に1回

Webhookフォーマット

Slack

URLにslack.comが含まれる場合、自動的に検出されます。

メッセージ例：

⚠️ Budget Warning: daily budget at 85.0% ($8.50 / $10.00)

フォーマット：

{
  "text": "⚠️ Budget Warning: daily budget at 85.0% ($8.50 / $10.00)",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "⚠️ Budget Warning: daily budget at 85.0% ($8.50 / $10.00)"
      }
    }
  ]
}

Discord

URLにdiscord.comが含まれる場合、自動的に検出されます。

埋め込み例：

タイトル： budget_warning
説明： ⚠️ Budget Warning: daily budget at 85.0% ($8.50 / $10.00)
色：アンバー (#FBBF24)
タイムスタンプ： 2026-03-05T10:30:00Z

フォーマット：

{
  "content": "⚠️ Budget Warning: daily budget at 85.0% ($8.50 / $10.00)",
  "embeds": [
    {
      "title": "budget_warning",
      "description": "⚠️ Budget Warning: daily budget at 85.0% ($8.50 / $10.00)",
      "timestamp": "2026-03-05T10:30:00Z",
      "color": 16432932
    }
  ]
}

汎用JSON

その他すべてのURLに使用されます。

フォーマット：

{
  "event": "budget_warning",
  "timestamp": "2026-03-05T10:30:00Z",
  "data": {
    "period": "daily",
    "spent": 8.5,
    "limit": 10.0,
    "percent": 85.0,
    "project": ""
  }
}

イベントデータ構造

予算警告 / 超過

{
  "event": "budget_warning",
  "timestamp": "2026-03-05T10:30:00Z",
  "data": {
    "period": "daily",
    "spent": 8.5,
    "limit": 10.0,
    "percent": 85.0,
    "action": "warn",
    "project": "my-project"
  }
}

プロバイダーダウン / アップ

{
  "event": "provider_down",
  "timestamp": "2026-03-05T10:30:00Z",
  "data": {
    "provider": "anthropic-primary",
    "status": "unhealthy",
    "error": "connection timeout",
    "latency_ms": 0
  }
}

フェイルオーバー

{
  "event": "failover",
  "timestamp": "2026-03-05T10:30:00Z",
  "data": {
    "from_provider": "anthropic-primary",
    "to_provider": "anthropic-backup",
    "reason": "rate limit exceeded",
    "session_id": "sess_abc123"
  }
}

日次サマリー

{
  "event": "daily_summary",
  "timestamp": "2026-03-05T00:00:00Z",
  "data": {
    "date": "2026-03-04",
    "total_cost": 25.50,
    "total_requests": 150,
    "total_input_tokens": 125000,
    "total_output_tokens": 35000,
    "by_provider": {
      "anthropic": 18.20,
      "openai": 7.30
    }
  }
}

プラットフォーム設定

Slack

Slack APIにアクセス
新しいアプリを作成または既存のアプリを選択
"Incoming Webhooks"を有効化
ワークスペースに Webhook を追加
Webhook URLをコピー（https://hooks.slack.com/で始まる）

設定：

{
  "webhooks": [
    {
      "enabled": true,
      "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
      "events": ["budget_warning", "provider_down"]
    }
  ]
}

Discord

Discordサーバー設定を開く
Integrations → Webhooksに移動
"New Webhook"をクリック
チャンネルを選択して Webhook URLをコピー

設定：

{
  "webhooks": [
    {
      "enabled": true,
      "url": "https://discord.com/api/webhooks/123456789/XXXXXXXXXXXXXXXXXXXX",
      "events": ["budget_exceeded", "failover"]
    }
  ]
}

カスタムWebhook

カスタム統合には汎用JSONフォーマットを使用：

{
  "webhooks": [
    {
      "enabled": true,
      "url": "https://your-server.com/webhook",
      "events": ["budget_warning", "daily_summary"],
      "headers": {
        "Authorization": "Bearer YOUR_SECRET_TOKEN",
        "X-Custom-Header": "value"
      }
    }
  ]
}

Web UI 設定

http://localhost:19840/settingsで Webhook 設定にアクセス：

"Webhooks"タブに移動
"Add Webhook"をクリック
Webhook URLを入力
購読するイベントを選択
（オプション）カスタムヘッダーを追加
"Test"をクリックして設定を検証
"Save"をクリック

APIエンドポイント

Webhookのリスト表示

GET /api/v1/webhooks

Webhookの追加

POST /api/v1/webhooks
Content-Type: application/json

{
  "enabled": true,
  "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "events": ["budget_warning", "provider_down"]
}

Webhookの更新

PUT /api/v1/webhooks/{id}
Content-Type: application/json

{
  "enabled": false
}

Webhookの削除

DELETE /api/v1/webhooks/{id}

Webhookのテスト

POST /api/v1/webhooks/{id}/test

設定を検証するためのテストメッセージを送信します。

メッセージ例

予算警告（Slack）

⚠️ Budget Warning: daily budget at 85.0% ($8.50 / $10.00)

予算超過（Discord）

🚫 Budget Exceeded: monthly limit of $200.00 reached (spent: $205.50). Action: block

プロバイダーダウン（Slack）

🔴 Provider Down: anthropic-primary is unhealthy. Error: connection timeout

プロバイダーアップ（Discord）

🟢 Provider Up: anthropic-primary is healthy again (latency: 1250ms)

フェイルオーバー（Slack）

🔄 Failover: Switched from anthropic-primary to anthropic-backup. Reason: rate limit exceeded

日次サマリー（Discord）

📊 Daily Summary (2026-03-04): 150 requests, $25.50 total cost, 125000 input / 35000 output tokens

ベストプラクティス

個別の Webhook を使用 — 異なるイベントタイプに対して異なる Webhook を作成
有効化前にテスト — 保存前に常に Webhook 設定をテスト
カスタム Webhook を保護 — HTTPSと認証ヘッダーを使用
Webhook 失敗を監視 — 通知が停止した場合、デーモンログを確認
機密データを避ける — Webhook URLにAPIキーやトークンを含めない
アラートを設定 — budget_exceededやprovider_downなどの重要なイベントを購読

トラブルシューティング

Webhookがメッセージを受信しない

設定で Webhook が有効化されていることを確認
URLが正しいことを確認（curlでテスト）
イベント設定が正しいことを確認
デーモンログで Webhook エラーを確認：tail -f ~/.zen/zend.log
API 経由で Webhook をテスト：POST /api/v1/webhooks/{id}/test

Slack Webhook が失敗する

Webhook URLがhttps://hooks.slack.com/で始まることを確認
Slack設定で Webhook が取り消されていないか確認
ワークスペースが受信 Webhook を無効化していないことを確認

curlでテスト：

curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
  -H 'Content-Type: application/json' \
  -d '{"text":"test"}'

Discord Webhook が失敗する

Webhook URLがhttps://discord.com/api/webhooks/で始まることを確認
Discord設定で Webhook が削除されていないか確認
Botがチャンネルに投稿する権限を持っていることを確認

curlでテスト：

curl -X POST https://discord.com/api/webhooks/YOUR/WEBHOOK/URL \
  -H 'Content-Type: application/json' \
  -d '{"content":"test"}'

カスタム Webhook が機能しない

エンドポイントがアクセス可能であることを確認（curlでテスト）
認証ヘッダーが正しいことを確認
エンドポイントがPOSTリクエストを受け入れることを確認
エンドポイントが2xxステータスコードを返すことを確認
エンドポイントログでエラーを確認

セキュリティ考慮事項

Webhook URLを保護 — Webhook URLを機密情報として扱う
HTTPSを使用 — Webhook エンドポイントには常にHTTPSを使用
署名を検証 — カスタム Webhook に署名検証を実装
レート制限 — Webhook エンドポイントにレート制限を実装
機密データをログに記録しない — 完全な Webhook ペイロードのログ記録を避ける

高度な設定

条件付きWebhook

異なるイベントを異なる Webhook に送信：

{
  "webhooks": [
    {
      "enabled": true,
      "url": "https://hooks.slack.com/services/CRITICAL/ALERTS",
      "events": ["budget_exceeded", "provider_down"]
    },
    {
      "enabled": true,
      "url": "https://hooks.slack.com/services/DAILY/REPORTS",
      "events": ["daily_summary"]
    },
    {
      "enabled": true,
      "url": "https://discord.com/api/webhooks/MONITORING",
      "events": ["failover", "provider_up"]
    }
  ]
}

認証用のカスタムヘッダー

{
  "webhooks": [
    {
      "enabled": true,
      "url": "https://your-server.com/webhook",
      "events": ["budget_warning"],
      "headers": {
        "Authorization": "Bearer YOUR_SECRET_TOKEN",
        "X-API-Key": "your-api-key",
        "X-Webhook-Source": "gozen"
      }
    }
  ]
}

機能​

設定​

イベントタイプ​

Webhookフォーマット​

Slack​

Discord​

汎用JSON​

イベントデータ構造​

予算警告 / 超過​

プロバイダーダウン / アップ​

フェイルオーバー​

日次サマリー​

プラットフォーム設定​

Slack​

Discord​

カスタムWebhook​

Web UI 設定​

APIエンドポイント​

Webhookのリスト表示​

Webhookの追加​

Webhookの更新​

Webhookの削除​

Webhookのテスト​

メッセージ例​

予算警告（Slack）​

予算超過（Discord）​

プロバイダーダウン（Slack）​

プロバイダーアップ（Discord）​

フェイルオーバー（Slack）​

日次サマリー（Discord）​

ベストプラクティス​

トラブルシューティング​

Webhookがメッセージを受信しない​

Slack Webhook が失敗する​

Discord Webhook が失敗する​

カスタム Webhook が機能しない​

セキュリティ考慮事項​

高度な設定​

条件付きWebhook​

認証用のカスタムヘッダー​

機能

設定

イベントタイプ

Webhookフォーマット

Slack

Discord

汎用JSON

イベントデータ構造

予算警告 / 超過

プロバイダーダウン / アップ

フェイルオーバー

日次サマリー

プラットフォーム設定

Slack

Discord

カスタムWebhook

Web UI 設定

APIエンドポイント

Webhookのリスト表示

Webhookの追加

Webhookの更新

Webhookの削除

Webhookのテスト

メッセージ例

予算警告（Slack）

予算超過（Discord）

プロバイダーダウン（Slack）

プロバイダーアップ（Discord）

フェイルオーバー（Slack）

日次サマリー（Discord）

ベストプラクティス

トラブルシューティング

Webhookがメッセージを受信しない

Slack Webhook が失敗する

Discord Webhook が失敗する

カスタム Webhook が機能しない

セキュリティ考慮事項

高度な設定

条件付きWebhook

認証用のカスタムヘッダー