電話・チャット — ルーム管理・着信拒否番号、電話番号設定画面の使い方に戻る

開発者向け

着信 Webhook の仕様

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

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

1

仕組みと特性

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

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

送信先の登録

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

着信 Webhook 設定画面。送信先の登録、署名の鍵、送信元 IP アドレス、通知の再送状況が並ぶ
着信 Webhook 設定。対象・送信タイミング・送信先 URL・ラベルを登録します
  • 送信先 URL は https:// のみ登録できます。インターネットに公開されているアドレスを指定してください。社内ネットワークのアドレスは登録できません。
  • 対象を「組織全体」にすると、その組織のすべての着信先電話番号に適用されます。電話番号を選ぶと、その電話番号だけを上書きします。
  • 編集で変更できるのは URL とラベルのみです。対象・タイミングを変えるときは、削除して登録し直してください。

署名の鍵の発行

  1. 着信 Webhook 設定画面の「署名の鍵」で「発行」を押します。
    署名の鍵の欄。未発行で通知は署名なしで送信されることと、発行のボタンが並ぶ
  2. 表示された鍵をコピーのボタンでコピーし、受信側に登録します。発行した時点から、すべての通知に署名を付けて送ります。
    署名の鍵の欄。鍵の先頭とコピーのボタン、再発行のボタンが並ぶ
  3. 鍵を変えるときは「再発行」を押し、確認の画面でもう一度「再発行」を押します。 古い鍵はその時点で使えなくなります。 受信側の鍵を新しい鍵に更新するまで、署名の検証に失敗します。
    署名の鍵を再発行する確認の画面。キャンセルと再発行のボタンが並ぶ

受信側での確かめ方は「署名を確かめる」を参照してください。

3

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

送信タイミング

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

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

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

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

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

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

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

4

リクエスト仕様

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

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

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

フィールド一覧

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

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

例: 着信切断時(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": "1721380000.123",
  "calldate": "",
  "calldate_answer": "",
  "calldate_end": "",
  "call_status": "",
  "caller_phonenumber": "",
  "callee_phonenumber": "05000000000",
  "transferer_phonenumber": "",
  "transferee_phonenumber": "",
  "call_duration": ""
}
6

受信側の実装ヒント

  • すぐに 2xx を返す。 3 秒で打ち切られ、呼出時・応答時は通話フローと同期します。DB 書き込み・外部連携などの重い処理は、いったん受け取って 2xx を返してから非同期に処理してください。
  • 署名を確かめる。 着信 Webhook の設定画面で署名の鍵を発行すると、X-Webhook-Signature: t=時刻,v1=署名 を付けて送ります。時刻.本文 を鍵で HMAC-SHA256 した 16 進が v1 と一致し、時刻が 5 分以内なら、正しい送信元から届いた通知です。形式は配信の Webhook と同じです。鍵を発行していない間は署名を付けません。あわせて送信元 IP でアクセス制限を設けることもできます。署名の鍵と送信元 IP アドレスは着信 Webhook の設定画面に表示されます。
  • タイミングは request_timing で分岐する。 1 つの URL をタイミングで共用できます。タイミングごとに別の URL を登録しても構いません。
  • 確実な記録は切断時(hangup)で。 呼出時・応答時は通話フローと同期で送り、タイムアウトも短く、再送もしません。取りこぼしうる前提で、確定した情報は切断時のペイロードを正としてください。

受信の最小例(PHP)

<?php
// 署名を確かめる(鍵は着信 Webhook の設定画面で発行したもの)
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, getenv('NARUKO_WEBHOOK_SECRET'));
if (! hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(401); exit;
}
$body = json_decode($raw, 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']。
}