メインコンテンツまでスキップ

Webhook 設定ガイド

Webhook を設定すると、通話のステータス変更やエラー発生などのイベントを、外部システム（Slack / Microsoft Teams / Email / 独自エンドポイント）にリアルタイムで通知できます。

クイックスタート​

最短手順で疎通確認するには、以下 3 ステップを実施してください。

1. Webhook を受信する最小 Node.js コード​

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const { eventType, body } = req.body;

  // エラー判定は body.errors の有無で
  if (Array.isArray(body.errors) && body.errors.length > 0) {
    console.error(`[${eventType}] callId=${body.data.callId} has errors`);
  } else {
    console.log(`[${eventType}] callId=${body.data.callId}`);
  }

  // 2xx を返さないと指数バックオフでリトライされます
  res.sendStatus(200);
});

app.listen(3000);

2. ダッシュボードで送信先を登録​

Recho ダッシュボードの「Webhook」ページで、上記エンドポイント URL を Custom タイプとして登録します。

3. 通知トリガーを ON​

「通知トリガー」セクションで、受信したいイベント（例: OUTBOUND_CALL_ERROR）を選択します。

これで疎通確認できる最小構成は完成です。以下、本格運用に必要な内容を続けて読んでください。

設定の流れ（詳細）​

  1. 送信先エンドポイントを登録する ダッシュボードの Webhook ページで「送信先エンドポイント」セクションから「新規作成」を選択し、エンドポイントタイプ（Slack / Teams / Email / Custom）と送信先 URL（またはメールアドレス）を入力します。

  2. 認証方式を選ぶ（Custom の場合） 独自エンドポイントには Bearer トークン認証または RSA 署名検証を設定できます。詳細は 認証方式 を参照してください。

  3. 通知トリガーを有効化する 「通知トリガー」セクションで、どのイベント（発信通話完了、エラー、着信開始など）で Webhook を発火させるかを選択します。

  4. 受信側を実装する 送信される Payload の仕様は Payload 仕様 を、実装サンプルは 受信サンプル を参照してください。

  5. テスト発火・本番運用 実際に通話を行うか、テストイベントを発火させて疎通を確認してください。

対応エンドポイントタイプ​

種別説明
SlackIncoming Webhook URL を指定すると、整形済みのメッセージが Slack チャンネルに投稿されます
Microsoft TeamsWorkflows / Incoming Webhook URL を指定すると、Teams チャンネルにアダプティブカード形式で投稿されます
Email送信先メールアドレスを指定すると、整形済みの本文がメールで送信されます
Custom任意の HTTPS エンドポイントに JSON を POST します。認証方式（Bearer / RSA 署名）を設定でき、最も柔軟に連携できます

配信の挙動​

  • 非同期配信: API 処理本体とは独立して非同期で送信されます。送信失敗が API のレスポンスに影響することはありません。
  • 同一通話内は FIFO 配信: 同一の callId に関するイベントは発火順 (FIFO) で配信されます。内部で FIFO キューを採用しており、ある通話の状態遷移（例: OUTBOUND_CALL_CALLING → OUTBOUND_CALL_COMPLETED）が逆順に届くことはありません。異なる通話間の到達順序は保証されません。
  • 失敗時はリトライ: 受信側が 408 / 429 / 5xx を返したり timeout した場合、指数バックオフで最大 6 回試行します。詳細は リトライ仕様 を参照してください。