開発者向け
Naruko の電話番号に外線着信があったとき、着信の各タイミングで、 登録した URL へ発着信情報を HTTP POST します。 CRM でのスクリーンポップ、着信ログ、自動処理のトリガなどに使えます。 送信先は電話番号ごとに設定できます。
設定画面: 着信 Webhook 設定 / 料金: 無料。外線着信と支払方法確定済に含まれます
着信が Naruko の電話設備に届くと、設定したタイミングで Naruko がお使いの URL へ JSON を POST します。
uniqueid を鍵にして、同じ通話を二重に処理しないようにしてください。X-Webhook-Signature を付けて送ります。確かめ方は「署名を確かめる」を参照してください。着信 Webhook 設定 画面で、対象(組織全体または電話番号)・送信タイミング・送信先 URL を登録します。組織管理者、または 「着信 Webhook」機能権限を付与された利用者が設定できます。

https:// のみ登録できます。インターネットに公開されているアドレスを指定してください。社内ネットワークのアドレスは登録できません。


受信側での確かめ方は「署名を確かめる」を参照してください。
| request_timing | 名称 |
|---|---|
| incoming_call_ringing | 着信呼出時 |
| incoming_call_answer | 着信応答時 |
| incoming_call_hangup | 着信切断時 |
着信応答時を送信するのは、 ルームへの着信・外線転送・AIエージェントが応答したときです。 IVR・留守電・トランク転送・リアルタイム応答では送信しません。 着信呼出時と着信切断時は、着信の動作にかかわらず送信します。
タイミングごとに値が入るフィールドは 5. ペイロードのフィールド定義 の表を参照してください。
着信があると、Naruko は着信先電話番号ごとの設定を優先し、無ければ組織全体の既定に フォールバックして 1 件だけ送信先を決めます。
例)電話番号 A に「切断時」個別設定があり、電話番号 B には無い場合 — A への着信は A の URL へ、B への着信は組織既定の URL へ送られます。
| メソッド | POST |
|---|---|
| Content-Type | application/json |
| ボディ | 下記のペイロード |
| タイムアウト | 接続 2 秒 / 全体 3 秒。超過した場合は打ち切り、切断時は再送の対象になります |
| 期待するレスポンス | 2xx。4xx / 5xx は失敗として記録し、切断時は再送します。通話は継続します |
| 認証・署名 | X-Webhook-Signature。鍵を発行したときだけ付けます |
どのタイミングでも同じ 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 | — | — | ● | 通話した秒数。 |
{
"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"
}{
"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": ""
}X-Webhook-Signature: t=時刻,v1=署名 を付けて送ります。時刻.本文 を鍵で HMAC-SHA256 した 16 進が v1 と一致し、時刻が 5 分以内なら、正しい送信元から届いた通知です。形式は配信の Webhook と同じです。鍵を発行していない間は署名を付けません。あわせて送信元 IP でアクセス制限を設けることもできます。署名の鍵と送信元 IP アドレスは着信 Webhook の設定画面に表示されます。request_timing で分岐する。 1 つの URL をタイミングで共用できます。タイミングごとに別の URL を登録しても構いません。受信の最小例(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']。
}