開発者向け

着信 Webhook の仕様

Naruko の電話番号に外線着信があったとき、着信の各タイミングで、登録した URL へ発着信情報を HTTP POST します。 CRM でのスクリーンポップ、着信ログ、自動処理のトリガなどに使えます。送信先は電話番号ごとに設定できます。

設定画面: 着信 Webhook 設定／料金: 無料。外線着信と支払方法確定済に含まれます

仕組みと特性

着信が Naruko の電話設備に届くと、設定したタイミングで Naruko がお使いの URL へ JSON を POST します。

通話フローと同期して送信します。 呼出時・応答時の Webhook は、通話をつなぐ処理の途中で実行されます。お使いのサーバーの応答が遅いと通話接続に影響しないよう、接続 2 秒・全体 3 秒で打ち切ります。
切断時だけ再送します。 送信に失敗したときは 10 秒後・20 秒後・30 秒後に最大 3 回送り直します。呼出時・応答時は再送しません。いま鳴っていることを伝える通知なので、遅れて届いても使えないためです。失敗しても通話はそのまま継続します。
再送した通知は設定画面で確認できます。 「通知の再送状況」に、日時・発信元・着信先・通話 ID と、再送中 / 再送成功 / 送信失敗のいずれかが表示されます。成功した 1 回目の送信は記録されないため、何も並んでいないのが正常な状態です。送信失敗の通話は、通話明細で内容を確認できます。
同じ通知が複数回届くことがあります。 受信できたのに 2xx を返せなかった場合、再送が届きます。uniqueid を鍵にして、同じ通話を二重に処理しないようにしてください。
署名ヘッダはありません。 現状、リクエストに認証・署名は付きません。受信側の保護は「6. 受信側の実装ヒント」を参照してください。
1 対象 × 1 タイミングにつき URL は 1 つ。 「組織全体」または電話番号ごとに、タイミング別で URL を登録します。

送信先の登録

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

送信先 URL は https:// のみ登録できます。
対象を「組織全体」にすると、その組織のすべての着信番号に適用されます。番号を選ぶと、その番号だけを上書きします。
編集で変更できるのは URL とラベルのみです。対象・タイミングを変えるときは、削除して登録し直してください。

送信タイミングと対象番号

送信タイミング

request_timing	名称
incoming_call_ringing	着信呼出時
incoming_call_answer	着信応答時
incoming_call_hangup	着信切断時

着信応答時を送信するのは、 ルームへの着信・外線転送・AIエージェントが応答したときです。 IVR・留守電・トランク転送・OpenAI Realtime 応答では送信しません。 着信呼出時と着信切断時は、着信の動作にかかわらず送信します。

タイミングごとに値が入るフィールドは 5. ペイロードのフィールド定義の表を参照してください。

番号ごとの設定とフォールバック

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

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

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

リクエスト仕様

メソッド	POST
Content-Type	application/json
ボディ	下記のペイロード
タイムアウト	接続 2 秒 / 全体 3 秒。超過したら打ち切り、切断時は再送の対象になります
期待するレスポンス	2xx。4xx / 5xx は失敗として記録し、切断時は再送します。通話は継続します
認証・署名	なし

ペイロードのフィールド定義

どのタイミングでも同じ 11 個のキーを持つ JSON を送ります。値は すべて文字列で、そのタイミングで確定していない項目は空文字になります。

フィールド一覧

● は値が入るタイミング、— はそのタイミングでは空文字になります。

キー	型	着信呼出時	着信応答時	着信切断時	説明
request_timing	string	●	●	●	どのタイミングの通知かを示します。値は incoming_call_ringing / incoming_call_answer / incoming_call_hangup のいずれかです。
uniqueid	string	—	●	●	通話の一意 ID。例: 1721380000.123。同じ通話なら、どのタイミングでも同じ値です。
calldate	string	—	●	●	着信した時刻。日本時間で、書式は YYYY-MM-DD HH:MM:SS です。
calldate_answer	string	—	●	●	応答時刻。無応答なら空。
calldate_end	string	—	—	●	通話が終了した時刻。
call_status	string	—	—	●	着信結果。例: ANSWERED / NO ANSWER / BUSY / FAILED。
caller_phonenumber	string	—	●	●	発信した相手の番号。
callee_phonenumber	string	●	●	●	着信を受けた、お使いの電話番号。番号ごとの設定の判定にも使われます。
transferer_phonenumber	string	—	—	●	転送があった場合の転送元番号。無ければ空。
transferee_phonenumber	string	—	—	●	転送があった場合の転送先番号。無ければ空。
call_duration	string	—	—	●	通話した秒数。

例: 着信切断時（incoming_call_hangup）

{
  "request_timing": "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": "05000000000",
  "transferer_phonenumber": "",
  "transferee_phonenumber": "",
  "call_duration": "175"
}

例: 着信呼出時（incoming_call_ringing）

{
  "request_timing": "incoming_call_ringing",
  "uniqueid": "",
  "calldate": "",
  "calldate_answer": "",
  "calldate_end": "",
  "call_status": "",
  "caller_phonenumber": "",
  "callee_phonenumber": "05000000000",
  "transferer_phonenumber": "",
  "transferee_phonenumber": "",
  "call_duration": ""
}

受信側の実装ヒント

すぐに 2xx を返す。 3 秒で打ち切られ、呼出時・応答時は通話フローと同期します。DB 書き込み・外部連携などの重い処理は、いったん受け取って 2xx を返してから非同期に処理してください。
署名が無いため URL 自体を秘密にする。 推測困難なパス（例: /hooks/naruko/8f3c…）やクエリのトークンを URL に含め、受信側で検証します。あわせて送信元 IP でアクセス制限を設けることもできます。送信元 IP アドレスは着信 Webhook の設定画面に表示されます。
タイミングは request_timing で分岐する。 1 つの URL をタイミングで共用できます。タイミングごとに別の URL を登録しても構いません。
確実な記録は切断時（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']。
}

着信の設定ガイドに戻る着信 Webhook を設定する