着信 Webhook の仕様

着信が Naruko の電話設備（Asterisk）に届くと、設定したタイミングで Naruko があなたの URL へ JSON を POST します。 Todoke の Webhook とは設計が異なるため、以下の特性を必ず把握してください。

• 通話フローと同期して送信します。 呼出時・応答時の Webhook は、通話をつなぐ処理の途中で実行されます。あなたのサーバーの応答が遅いと通話接続に影響しないよう、接続 2 秒・全体 3 秒で打ち切ります。
• 再送（リトライ）はありません。 1 回だけ送信し、失敗（タイムアウト・接続エラー・4xx/5xx）してもそのまま通話は継続します（fail-soft）。確実な受信が必要なら、切断時（hangup）を軸に設計してください。
• 署名ヘッダはありません。 現状、リクエストに認証・署名は付きません。受信側の保護は「6. 受信側の実装ヒント」を参照してください。
• 1 対象 × 1 タイミングにつき URL は 1 つ。 「組織全体（既定）」または電話番号ごとに、タイミング別で URL を登録します。

着信 Webhook 設定 画面で、対象（組織全体または電話番号）・送信タイミング・送信先 URL を登録します。組織管理者、または 「着信 Webhook」機能権限を付与された利用者が設定できます。

• 送信先 URL は https:// のみ登録できます（平文 http は不可）。
• 対象を「組織全体（既定）」にすると、その組織のすべての着信番号に適用されます。特定の番号を選ぶと、その番号だけを上書きします。
• 編集で変更できるのは URL とラベルのみ。対象・タイミングを変える場合は削除して作り直します。削除は無効化（論理削除）で、以後その設定は送信されません。

送信タイミング

対象番号とフォールバック（番号別設定）

着信があると、Naruko は着信番号（callee）ごとの設定を優先し、無ければ組織全体の既定に フォールバックして 1 件だけ送信先を決めます。

1. その着信番号に対する、そのタイミングの個別設定があればそれを使う。
2. 無ければ、組織全体（既定）のそのタイミングの設定を使う。
3. どちらも無ければ送信しません（何もしません）。

例）番号 A に「切断時」個別設定があり、番号 B には無い場合 — A への着信は A の URL へ、B への着信は組織既定の URL へ送られます。

どのタイミングでも同じ 10 個のキーを持つ JSON を送ります。値は すべて文字列で、そのタイミングで確定していない項目は空文字（""）になります。 ペイロードにタイミング名や組織 ID は含まれません（タイミングは登録した URL で区別してください）。

フィールド一覧

タイミング別の充足フィールド

● が値の入るフィールド、空欄はそのタイミングでは空文字になるフィールドです。

例: 着信切断時（incoming_call_hangup）

{
  "uniqueid": "1721380000.123",
  "calldate": "2026-07-19 10:00:00",
  "calldate_answer": "2026-07-19 10:00:05",
  "calldate_end": "2026-07-19 10:03:00",
  "call_status": "ANSWERED",
  "caller_phonenumber": "0312345678",
  "callee_phonenumber": "0312349002",
  "transferer_phonenumber": "",
  "transferee_phonenumber": "",
  "call_duration": "175"
}

例: 着信呼出時（incoming_call_ringing）

{
  "uniqueid": "",
  "calldate": "",
  "calldate_answer": "",
  "calldate_end": "",
  "call_status": "",
  "caller_phonenumber": "",
  "callee_phonenumber": "0312349002",
  "transferer_phonenumber": "",
  "transferee_phonenumber": "",
  "call_duration": ""
}

• すぐに 2xx を返す。 3 秒で打ち切られ、呼出時・応答時は通話フローと同期します。DB 書き込み・外部連携などの重い処理は、いったん受け取って 2xx を返してから非同期に回してください。
• 署名が無いため URL 自体を秘密にする。 推測困難なパス（例: /hooks/naruko/8f3c…）やクエリのトークンを URL に含め、受信側で検証します。可能なら Naruko の送信元 IP でアクセス制限してください。
• 冪等に処理する。 uniqueid は同一通話で共通です。同じ (uniqueid, タイミング) を二重に受けても安全なようにしてください。
• タイミングは URL で区別する。 ペイロードにタイミング名は入りません。タイミングごとに別 URL（別パス）を登録すると受信側の分岐が簡単です。1 つの URL を使い回す場合は、call_duration が入っていれば切断時、といった充足フィールドで判別します。
• 確実な記録は切断時（hangup）で。 呼出時・応答時は同期・短タイムアウト・再送なしのため取りこぼしうる前提で、確定情報は切断時のペイロードを正としてください。

受信の最小例（PHP）

<?php
// URL のトークンを検証（署名が無いため URL 秘匿で守る）
if (($_GET['token'] ?? '') !== getenv('NARUKO_WEBHOOK_TOKEN')) {
    http_response_code(404); exit;
}
$body = json_decode(file_get_contents('php://input'), true) ?? [];
// まず即 2xx を返す（重い処理は後回し）
http_response_code(204);
fastcgi_finish_request();

// 以降で非同期に処理（例: 切断時のみ記録）
if ($body['call_duration'] !== '') {
    // callee=$body['callee_phonenumber'] への着信が
    // caller=$body['caller_phonenumber'] から、結果 $body['call_status']、
    // $body['call_duration'] 秒で終了。uniqueid=$body['uniqueid'] で冪等化。
}