Webhook

Webhookを使うと、あなたのアカウントで何かが起きたときに、外部システムがKolleKからのHTTP呼び出しを受け取れます。今のうちから設定しておくことができ、このページではその方法を説明します。ただし、まずは次の段落を読んでください。ここが以降すべての前提になります。

現時点でできること

エンドポイントを登録すると、送信先URLと、そのエンドポイント専用の署名シークレットが保存されます。将来KolleKが実際にイベントを発火させるようになると、登録済みのすべての有効なエンドポイントに配信され、あなたのインスタンスから送られたものであることを受信側で検証できるよう署名が付きます。

Webhookエンドポイントは、アカウント全体ではなく、あなたのユーザーに紐づきます。

エンドポイントを登録する

アプリでプロフィール設定を開き、Webhookに移動します。受信側がリッスンしているURLを、後で分かるようにラベルを付けて追加します。各エンドポイントには、作成時に生成される64文字の署名シークレットが割り当てられます。これを受信側とともに保管してください。

運用者は、コマンドラインからもエンドポイントを作成できます。

php artisan kollek:create-webhook-endpoint you@example.com https://example.com/hooks --label="My receiver"

このコマンドは、エンドポイントIDと署名シークレットを出力します。

受信側が想定しておくべきペイロード

すべての配信は、次の形をしたJSONの POST です。

{
  "event": "example.event",
  "happened_at": "2026-07-20T14:30:00+00:00",
  "data": {}
}

• event: 何が起きたかを表す名前です。現時点ではイベント名はまだ定義されていません。
• happened_at: 発生時刻を表すISO 8601形式のタイムスタンプです。
• data: そのイベントに対応するペイロードです。

署名の検証

各配信には Signature ヘッダーが付きます。これは、生のリクエストボディに対して、エンドポイントの署名シークレットを使って計算されたHMAC SHA256ハッシュです。受信側でも同じハッシュを計算し、比較してください。値が一致しない場合はそのリクエストを破棄してください。あなたのインスタンスから送られたものではないということです。

$computed = hash_hmac('sha256', $rawRequestBody, $signingSecret);

if (! hash_equals($computed, $request->header('Signature'))) {
    abort(401);
}

配信と再試行

配信はキューに入れられ、バックグラウンドで送信されます。失敗した配信は、指数バックオフを伴って最大3回まで再試行されます。受信側は、2xxのステータスですぐに応答し、実際の処理は非同期で行うようにしてください。

セルフホストのインスタンスでは、配信はキューワーカー上で実行されるため、キューロールが稼働している必要があります。Dockerでインストール を参照してください。

次に読むページ

• 機能ステータスページで、何がすでに稼働していて、何が保留中かを確認しましょう。
• その間に APIで認証する から始めて、APIを使った開発を進めましょう。