商談が完了すると、ゴリラセールスは商談データ・要約・BANT 情報をまとめたイベント（meeting.completed）を、 登録済みの受信 URL へ署名付き POST で通知します。受信側はこの通知を受け取り、自社の CRM やデータ基盤へ連携できます。

• 通知は HTTPS の受信エンドポイント URL に対して送られます。
• 各エンドポイントには固有の signing secret（whsec_...）が発行され、受信側はこれを使ってリクエストの署名を検証します。
• 署名方式は Standard Webhooks 準拠です。準拠ライブラリでの検証も、自前実装での検証も可能です。
• 日時はすべて UTC の ISO 8601 文字列（例: 2026-01-15T10:00:00.000Z）で送られます。

通知される具体的なペイロード構造は、本ページ下部の Webhooks セクション（meeting.completed / test.ping）を参照してください。

受信を始めるには、管理画面から受信エンドポイントを登録します。

1. 管理画面の 「組織設定 > Webhook 連携」 を開きます。
2. 受信する URL を登録します。
   • URL は HTTPS のドメインのみ登録できます（IP アドレス・localhost は登録できません）。
   • 1 つの組織につき 最大 5 件まで登録できます。
   • 同一 URL の重複登録はできません。
3. 登録すると、そのエンドポイント固有の signing secret（whsec_...）が発行されます。

signing secret（whsec_...）は、受信したリクエストが本当にゴリラセールスから送られたものかを検証するための鍵です。

• 安全に保管してください。 環境変数やシークレットマネージャーに格納し、ソースコードやログに直書きしないでください。
• 漏洩が疑われる場合は、管理画面から secret を再生成できます。再生成すると古い secret では検証できなくなるため、受信側の secret も差し替えてください。

「組織設定 > Webhook 連携」の各エンドポイント行の 「テスト送信」 から、実際に受信できるかを確認できます。 送信するイベント種別は 2 種類から選べます。

• 疎通確認（test.ping） — 軽量な疎通確認用のペイロード。まず受信できること・2xx を返せることの確認に使います。
• サンプルデータ（meeting.completed） — 架空のダミーデータ（固定 UUID・架空の会社名/氏名/要約/BANT/アクションアイテム）を含む、本番と同一構造の meeting.completed ペイロード。受信側のパース・マッピング実装を本番前に検証できます。

補足:

• 無効化されたエンドポイントにはテスト送信できません。
• テスト送信も本番と同じ signing secret で署名されるため、署名検証の実装をそのまま試せます。
• テスト送信の結果は、管理画面の配信ログに記録されます。

通知されるイベントは次の 2 種類です。ペイロードの詳細スキーマは本ページ下部の Webhooks セクションを参照してください。

すべてのペイロードは JSON オブジェクトで、トップレベルに event（イベント種別文字列）・tenantId・occurredAt を含みます。

各リクエストには、Content-Type（application/json）に加えて、以下の署名関連ヘッダが付与されます。

signing secret は whsec_ プレフィックス + base64 文字列です（例: whsec_MfKQ9r8...）。

受信側は、登録時に発行された signing secret を使い、以下の手順で HMAC を再計算して署名の一致を確認します。

1. 署名対象文字列をピリオド区切りで組み立てます。

   {webhook-id}.{webhook-timestamp}.{リクエストボディ生文字列}
   

   ボディは受信した生の JSON 文字列をそのまま使います（再シリアライズしないでください）。

2. signing secret から whsec_ プレフィックスを外し、残りを base64 デコードしたバイト列を HMAC 鍵にします。

3. 鍵で署名対象文字列を HMAC-SHA256 し、結果を base64 エンコードします。

4. 受信した webhook-signature（v1,<署名> 形式）から、バージョン接頭辞 v1, を外した署名と、手順 3 の結果を定数時間比較します。

署名時刻は webhook-timestamp（Unix 秒）に載っています。リプレイ攻撃を防ぐため、 Standard Webhooks の推奨に従い、現在時刻との差が概ね ±5 分（300 秒）を超えるリクエストは拒否することを推奨します。

import { createHmac, timingSafeEqual } from "node:crypto";

/**
 * Standard Webhooks 署名を検証する。
 * @param rawBody 受信した生のリクエストボディ文字列（パース前）
 * @param headers webhook-id / webhook-timestamp / webhook-signature
 * @param secret 登録時に発行された signing secret（whsec_...）
 */
export function verifyWebhookSignature(
  rawBody: string,
  headers: {
    "webhook-id": string;
    "webhook-timestamp": string;
    "webhook-signature": string;
  },
  secret: string,
): boolean {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatureHeader = headers["webhook-signature"];

  // リプレイ対策: timestamp が許容範囲内かを確認（±300 秒）
  const nowSec = Math.floor(Date.now() / 1000);
  const sentSec = Number(timestamp);
  if (!Number.isFinite(sentSec) || Math.abs(nowSec - sentSec) > 300) {
    return false;
  }

  // 署名対象文字列
  const signedContent = `${id}.${timestamp}.${rawBody}`;

  // secret から whsec_ を外して base64 デコードしたバイト列を鍵にする
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(signedContent, "utf8")
    .digest("base64");

  // webhook-signature は "v1,<sig> v2,<sig> ..." のようにスペース区切りで
  // 複数入りうる。バージョンが v1 のエントリのみを対象に、定数時間で比較する。
  return signatureHeader.split(" ").some((entry) => {
    const [version, sig] = entry.split(",");
    if (version !== "v1" || !sig) return false;
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

• まず 2xx を速やかに返す。 成功判定は HTTP 2xx です。受信後の重い処理（DB 書き込み・外部連携など）は非同期に回し、 まず 2xx を返してください。応答が 10 秒を超えるとタイムアウト扱いになり、リトライされます。
• 署名を必ず検証する。 受信したら署名検証を行い、検証に失敗したリクエストは拒否してください。 ボディはパース前の生文字列で検証します。
• webhook-id で冪等化する。 リトライにより、同一の配信が複数回届くことがあります。 webhook-id（配信 ID）を冪等化キーに使い、二重処理を防いでください。
• 送信元 IP は固定されていません。 送信元 IP アドレスによる許可リスト制御は想定していません。 認証は署名検証で行ってください。
• 未知フィールド・null に耐える。 フィールドの追加や null 値がありえます。 未知のキーは無視し、null 許容フィールドは存在を前提にせず扱ってください。

配信・リトライ仕様

本番配信（meeting.completed）

• 成功判定は HTTP 2xx です。
• 失敗時は最大 5 回試行し、指数バックオフで再送します（初回失敗から 30 秒 → 60 秒 → 120 秒 → 240 秒）。
• リトライ判定:
  • 2xx → 成功で確定。
  • 恒久 4xx（408 / 429 を除く 4xx） → 失敗で確定し、リトライしません。
  • 5xx / 408 / 429 / ネットワークエラー / タイムアウト（10 秒） → リトライ対象。最大試行に達したら失敗で確定します。
• リダイレクト（3xx）は追従しません（失敗扱い）。受信 URL は最終的な URL を登録してください。
• 再送されるボディは初回と同一です（試行間で内容は変わりません）。

• 管理画面からのテスト送信は、同期的に 1 回だけ送信します（自動リトライはありません）。
• 結果は本番配信と同じ配信ログに記録されます。

管理画面の配信ログで、各配信の成否・イベント種別・応答内容を確認できます。 失敗した配信は、管理画面から手動で再送できます。

Q. 通知が届きません。

• 受信エンドポイントが無効化されていないかを、管理画面「組織設定 > Webhook 連携」で確認してください。無効化されたエンドポイントには配信されません。
• 管理画面の配信ログで、配信が試行されているか・どの応答（ステータスコード）が返っているかを確認してください。
• まず テスト送信（test.ping） で疎通を確認し、受信側が 2xx を返せているかを切り分けてください。
• 受信 URL がリダイレクト（3xx）を返していないか確認してください。リダイレクトは追従されません。

Q. 署名検証に失敗します。

• 検証にはパース前の生のリクエストボディを使っているか確認してください。JSON を再シリアライズすると署名が一致しません。
• signing secret を再生成した場合、受信側の secret も新しいものに差し替える必要があります。古い secret では検証に失敗します。
• webhook-timestamp の許容範囲（±5 分）でリクエストが拒否されていないか、サーバーの時刻同期（NTP）を確認してください。

Q. 同じ商談の通知が複数回届きました。

• リトライや再送により、同一の配信が複数回届くことがあります。webhook-id を冪等化キーに使い、二重処理を防いでください。