Webhook

凍結されたサーフェス（ダッシュボード UI）

クラウドダッシュボードの専用 Webhook ページは、明示的な製品判断（2026-07-04、リポジトリの docs/FROZEN_SURFACES.md を参照）により、現在 凍結 されています: サイドバーの項目は非表示になり、/webhooks は /dashboard にリダイレクトされます。以下で説明する Webhook API と配信パイプラインは引き続き稼働し、維持されます。ただし、凍結が解除されるまで、新しい Webhook 機能の作業は計画されていません。ここに文書化された REST API サーフェスを通じて Webhook を管理してください。

Cloud Only

Webhook は Cloud バージョン でのみ利用可能です。

Webhook を使うと、ADHDev Cloud がマシンおよびエージェントのイベントを、あなた自身の HTTP エンドポイントにプッシュできます。

現在の重要な動作:

• Webhook API は稼働中です。
• 専用の /webhooks ダッシュボードページは、現在は安定した標準ナビゲーションサーフェスではありません。
• ペイロード、イベント、配信履歴の構造の正式な契約としては、REST API リファレンス を使ってください。
• Webhook の作成/切り替え/削除/テストのアクションは、最近のログインによって保護されたクラウドアカウントの操作であり、API キーではなく新鮮なダッシュボードセッションの JWT が必要です。

Webhook の作成

現在サインインしているクラウドダッシュボードセッションから Webhook を作成してください。基盤となるリクエストボディは次のとおりです:

{
  "url": "https://example.com/hooks/adhdev",
  "events": ["agent:generating_completed", "agent:waiting_approval"]
}

古いブラウザセッションから、または API キーで、変更を伴う Webhook エンドポイントを呼び出すと、サーバーはフックをプロビジョニングする代わりに 403 RECENT_LOGIN_REQUIRED を返します。

作成レスポンスは次を返します:

• Webhook レコード
• 署名検証のために一度だけ表示される secret

サポートされているすべてのイベントを購読するには、events に ["*"] を使ってください。

イベント

イベント	トリガー
agent:generating_started	エージェントが応答の生成を開始した
agent:generating_completed	エージェントが生成を完了した
agent:waiting_approval	エージェントが承認を待っている
agent:error	エージェントがエラーに遭遇した
webhook:test	テスト配信が明示的にリクエストされた

ペイロード形式

{
  "event": "agent:generating_completed",
  "payload": {
    "chatTitle": "Claude Code · myproject",
    "ideType": "claude-code",
    "duration": 42,
    "timestamp": 1714000000000
  },
  "timestamp": 1714000000000
}

署名の検証

各 Webhook リクエストには次が含まれます:

• X-ADHDev-Signature
• X-ADHDev-Event

署名の形式:

X-ADHDev-Signature: t=1714000000000,v1=a3f9c2b1...

生のリクエストボディ に対して検証してください。

Node.js

import crypto from 'crypto'

function verifySignature(body, signature, secret) {
  const parts = Object.fromEntries(signature.split(',').map((p) => p.split('=')))
  const timestamp = parts.t
  const received = parts.v1
  const payload = `${timestamp}.${body}`
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(received),
    Buffer.from(expected)
  )
}

// Express の例
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-adhdev-signature']
  const body = req.body.toString('utf8')
  if (!verifySignature(body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature')
  }
  const event = JSON.parse(body)
  // イベントを処理...
  res.sendStatus(200)
})

Python

import hmac
import hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in signature.split(','))
    timestamp = parts.get('t', '')
    received = parts.get('v1', '')
    payload = f"{timestamp}.{body.decode('utf-8')}".encode()
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received, expected)

# Flask の例
@app.route('/webhook', methods=['POST'])
def webhook():
    sig = request.headers.get('X-ADHDev-Signature', '')
    if not verify_signature(request.data, sig, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    event = request.get_json()
    # イベントを処理...
    return '', 200

Webhook のシークレットは、Webhook の作成時に一度だけ表示されます — 安全に保管してください。

管理エンドポイント

GET    /api/v1/webhooks
POST   /api/v1/webhooks
PATCH  /api/v1/webhooks/{webhookId}
DELETE /api/v1/webhooks/{webhookId}
GET    /api/v1/webhooks/{webhookId}/deliveries?limit=20
POST   /api/v1/webhooks/{webhookId}/test

GET エンドポイントが最も安全な自動化サーフェスです。変更を伴うエンドポイント（POST、PATCH、DELETE、test）は、最近のログインによって保護されたダッシュボードセッションの操作です。

リトライポリシー

失敗した配信は、指数バックオフで最大 3 回リトライされます。

プラン制限

プラン	最大 Webhook 数
Free	2
Pro	10
Team	50
Enterprise	無制限