Webhookを利用することで、電話の着信があったときに任意のアプリケーションで通知を受け取ることができます。
Webhook通知の仕様
基本情報
HTTPメソッド：POST
コンテンツタイプ：application/json
リクエストヘッダー
Content-Type: application/json
X-Fondesk-Signature: <HMAC署名>
X-Fondesk-Timestamp: <通知を送信した時刻のタイムスタンプ>
ペイロードの例
{
"callerName": "山田太郎",
"duration": 85,
"from": "+81312345678",
"id": "<着信のID>",
"receivedAt": 1731059738,
"recording": {
"duration": 15,
"transcription": "いつもお世話になっております。フォンデスクの山田です。メールをお送りしたのでご確認ください。よろしくお願いします。"
},
"tags": ["重要", "要対応"],
"url": "https://ivr.fondesk.jp/console/<ロボットのID>/calls/<着信のID>"
}
ペイロードのプロパティ
プロパティ | 型 | 説明 |
callerName | string | null | 発信者の名前。電話番号に紐づく連絡先が登録されている場合に設定されます |
duration | number | null | 通話時間（秒）。通話が成立しなかった場合はnullになります |
from | string | null | 発信者の電話番号。国際電話番号形式（E.164形式）で提供されます |
id | string | null | 着信のID。テスト通知ではnullになります |
receivedAt | number | 着信を受けた時刻（Unix時間） |
recording | object | undefined | 録音に関する情報。録音がない場合は設定されません |
recording.duration | number | 録音の長さ（秒） |
recording.transcription | string | 音声の文字起こし内容 |
shortMessage | object | undefined | 送信したショートメッセージに関する情報。ショートメッセージの送信がない場合は設定されません |
shortMessage.text | string | 送信したメッセージの内容 |
shortMessage.numSegments | number | ショートメッセージは内容が約70文字ごとに分割されて送信されます。その際の分割数です |
shortMessage.error | 'InvalidNumber' | 'TestCall' | 'Unknown' | ショートメッセージが送信できなかった場合の理由 |
transfer | object | undefined | 通話の転送に関する情報。転送がない場合は設定されません |
transfer.numbers | string[] | 転送先の電話番号の配列。国際電話番号形式（E.164形式）で提供されます |
transfer.connectedNumber | string | null | 転送に応答した相手の電話番号。国際電話番号形式（E.164形式）で提供されます |
transfer.duration | number | null | 通話時間（秒）。通話が成立しなかった場合、およびfondesk専用電話番号に転送した場合はnullになります |
transfer.error | 'InvalidNumber' | 'Forbidden' | 'TestCall' | 'Unknown' | 転送ができなかった場合の理由 |
tags | string[] | 通話に付与されたタグの配列 |
url | string | null | 通話詳細画面のURL。テスト通知ではnullになります |
設定方法
設定画面を開き、「新しい通知先を追加」から「Webhook」を選択してください。
以下の項目を入力します：
URL：Webhookを受信するエンドポイントのURL
シークレット：HMAC署名の生成に使用する文字列
「通知先を追加」を押して設定を保存します
署名の検証
通知の信頼性を確保するため、各リクエストにはHMAC署名が含まれます。この署名を検証することで、リクエストの改ざんを防ぐことができます。
以下は、Node.jsでHMAC署名を検証するサンプルコードです。
const crypto = require('crypto');
function validateSignature(signature, timestamp, payload, secret) {
const hmac = crypto.createHmac('sha256', secret);
hmac.update(`${timestamp}:${payload}`);
const expectedSignature = hmac.digest('hex');
return signature === expectedSignature;
}
// Expressでの使用例
app.post('/webhook', (req, res) => {
const signature = req.headers['x-fondesk-signature'];
const timestamp = req.headers['x-fondesk-timestamp'];
const payload = JSON.stringify(req.body);
const secret = 'あなたの設定したシークレット';
const isValid = validateSignature(signature, timestamp, payload, secret);
if (isValid) {
// Webhook通知の内容を処理する
console.log('Webhook通知を受信しました:', req.body);
res.status(200).send('OK');
} else {
res.status(401).send('署名が無効です');
}
});
エラーハンドリング
通知が失敗した場合、自動的に最大5回の再試行が行われます
30秒以内にレスポンスがない場合、タイムアウトとして扱われます
HTTPステータスコード200以外は失敗として扱われ、再試行の対象となります
同じ通知が複数回届く可能性があるため、べき等性を考慮した実装を行ってください