ペイロード仕様

配信形式

HTTPS POST で JSON ボディが送信されます。Content-Type は application/json。

サンプル Payload (Custom エンドポイント)

{
  "projectId": "3c9acfb1-c6b7-4bbc-b6c3-628af54d56c1",
  "webhookEndpoint": {
    "id": "ep-001",
    "name": "本番通知",
    "endpointType": "CUSTOM",
    "target": "https://example.com/webhook",
    "contentKey": null
  },
  "eventType": "OUTBOUND_CALL_ERROR",
  "body": {
    "subject": "[Recho] 発信通話エラー",
    "text": "[Recho] 発信通話エラー\n━━━━━━━━━━━━━━\ncallId: abc-123\ncallStatus: CALLING\ncallSid: CA94b51...\nclientId: client-1\n━━━━━━━━━━━━━━\nエラー一覧:\n  - [NETWORK_ERROR] Connection timed out (phase: CONNECTING)\n━━━━━━━━━━━━━━\n時刻: 2026-05-12 10:24:00",
    "data": {
      "callId": "abc-123",
      "callStatus": "CALLING",
      "callSid": "CA94b51...",
      "clientId": "client-1"
    },
    "errors": [
      {
        "code": "NETWORK_ERROR",
        "message": "Connection timed out",
        "timestamp": "2026-05-12T10:23:45.000Z",
        "where": "OutboundCallAdapter.connect",
        "phase": "CONNECTING",
        "stacktrace": ""
      }
    ]
  },
  "authConfig": { "authType": "NONE" }
}

注記

Slack / Teams / Email の場合は内部で適切な形式に変換されます（Custom のみがこの構造を直接受け取ります）。

TypeScript 型定義

上のサンプルと同じ構造の型定義です:

type WebhookPayload = {
  projectId: string;
  webhookEndpoint: WebhookEndpoint;
  eventType: EventType; // 'OUTBOUND_CALL_COMPLETED' など全 21 種類（削除予定）
  body: WebhookBody;
  authConfig: AuthConfig;
};

type WebhookEndpoint = {
  id: string;
  name: string;
  endpointType: 'SLACK' | 'TEAMS' | 'EMAIL' | 'CUSTOM';
  target: string;
  contentKey: string | null;
};

type WebhookBody = {
  subject: string;
  text: string;
  data: Record<string, string>;
  errors?: CallError[]; // エラー時のみ
};

type CallError = {
  code: string; // エラーコード一覧のいずれかの値（/webhooks/error-codes 参照）
  message: string;
  timestamp: string; // ISO 8601 (UTC)
  where: string;
  phase: string;
  stacktrace: string;
};

type AuthConfig = {
  authType: 'NONE' | 'BEARER' | 'SIGNATURE_RSA_SHA256';
};

type EventType =
  // 発信通話 (OUTBOUND)
  | 'OUTBOUND_CALL_WAITING_FOR_CACHE'
  | 'OUTBOUND_CALL_PENDING'
  | 'OUTBOUND_CALL_REQUESTED'
  | 'OUTBOUND_CALL_CALLING'
  | 'OUTBOUND_CALL_CLOSING'
  | 'OUTBOUND_CALL_COMPLETED'
  | 'OUTBOUND_CALL_EXPIRED'
  | 'OUTBOUND_CALL_NO_RESPONSE'
  | 'OUTBOUND_CALL_CANCELED'
  | 'OUTBOUND_CALL_BUSY'
  | 'OUTBOUND_CALL_UNREACHABLE'
  | 'OUTBOUND_CALL_MAX_ATTEMPTS_REACHED'
  | 'OUTBOUND_CALL_ERROR'
  | 'OUTBOUND_CALL_VOICEMAIL_REACHED'
  | 'OUTBOUND_CALL_HEALTHCHECK_FAILED'
  // 着信通話 (INBOUND)
  | 'INBOUND_CALL_CONNECTING'
  | 'INBOUND_CALL_CALLING'
  | 'INBOUND_CALL_CLOSING'
  | 'INBOUND_CALL_COMPLETED'
  | 'INBOUND_CALL_CONCURRENCY_LIMIT_EXCEEDED'
  | 'INBOUND_CALL_ERROR';

トップレベルフィールド

フィールド	型	用途
projectId	string	発火元の project ID (UUID)。マルチプロジェクト運用時のルーティングや権限チェックに使う想定
webhookEndpoint	WebhookEndpoint	配信先エンドポイントの設定スナップショット。マルチエンドポイント運用時に「どの設定経由で届いた通知か」を識別する用途
eventType	EventType	イベント種別。将来のリリースで削除予定（後述 参照）。値の一覧は上の TypeScript 型定義（EventType）を参照
body	WebhookBody	通知本文（後述）
authConfig	AuthConfig	このリクエストの認証方式の参照情報。実際の認証検証はリクエストヘッダ側で行う（認証方式 参照）。payload 側はあくまで「何方式で署名されたか」を示すメタ

webhookEndpoint フィールド

フィールド	型	用途
id	string	エンドポイントの ID（Recho 内部の主キー）。ログ突合や問い合わせ時に使用
name	string	エンドポイント名（ダッシュボードでの表示名）
endpointType	'SLACK' | 'TEAMS' | 'EMAIL' | 'CUSTOM'	エンドポイント種別。Custom のときのみこの payload 構造をそのまま受け取る
target	string	設定された宛先（Custom: URL / Slack/Teams: Incoming Webhook URL / Email: メールアドレス）。情報用
contentKey	string | null	テンプレート種別キー。null の場合は標準フォーマット

authConfig フィールド

フィールド	型	用途
authType	'NONE' | 'BEARER' | 'SIGNATURE_RSA_SHA256'	この配信に適用された認証方式の種別。認証情報の本体（トークン / 署名）はリクエストヘッダ側に付与される

authType の取り得る値:

値	意味
NONE	認証なし
BEARER	Bearer トークン認証（Authorization ヘッダ）
SIGNATURE_RSA_SHA256	RSA-SHA256 署名検証（X-Recho-Signature 系ヘッダ）

各方式の詳細と受信側の検証実装は 認証方式 を参照してください。

body フィールド

フィールド	型	用途
subject	string	表示用の件名。メール送信時の Subject、UI 上の見出しなどに使う想定
text	string	表示用の整形済み本文（人間可読）。改行 (\n) と区切り線入り。Slack / Teams 投稿、ログ表示、メール本文などに流すのが想定用途。機械的にパースしないこと
data	Record<string, string>	機械可読な識別情報。callId / callStatus / callSid / clientId 等を持つフラットな string→string マップ。プログラム側はここを参照する
errors	Array<CallError> | undefined	エラー時のみ含まれる配列。受信側は body.errors?.length でエラー判定 → 詳細ログや通知に流用

body.data フィールド（通話識別情報）

フィールド	型	用途
callId	string	通話 ID（一意）。外部システムで通話を識別する主キー。同じ callId のイベントは FIFO で配信される（設定ガイド 参照）
callStatus	string	通知時点の通話ステータス。値の一覧は 通話ステータス一覧 参照。エラー判定には使えない（errors 配列の有無で行うこと）
callSid	string	電話回線プロバイダ側の通話 ID（無い場合は空文字）。プロバイダ側ログとの突合に使う想定
clientId	string	クライアント識別子（任意・無い場合は空文字）。発信時に指定したアプリケーション側 ID をそのまま透過させるためのフィールド

eventType（イベント種別）

削除予定

eventType フィールドは将来のリリースでの削除を予定しています。削除時期・移行方法は確定次第、本ドキュメントで告知します。新規実装で eventType に依存したロジックを組む場合はこの点にご留意ください。

Webhook は「通話に何かが起きたとき」に送信されます。発信・着信それぞれの通話は、開始から終了までの間にステータスが遷移していき（通話ステータス一覧 参照）、この通話上の出来事（ステータス遷移や失敗事由の確定）が Webhook 配信のトリガーです。payload の eventType には「どの出来事がこの通知を発生させたか」がそのまま入ります。

例えば発信した相手が話し中だった場合、その通話について OUTBOUND_CALL_BUSY を eventType に持つ Webhook が 1 件配信されます。

値は {OUTBOUND|INBOUND}_CALL_{出来事} の形式で全 21 種類（発信 15 + 着信 6）です。Webhook 設定ページの「通知トリガー」セクションに並ぶ項目はこの eventType と 1 対 1 対応しており、ON にした出来事の通知だけが配信されます（OFF のものは配信されません）。

eventType の全 21 値は本ページ上部の TypeScript 型定義を参照してください。

body.errors[] フィールド（エラー詳細）

エラー発生時のみ含まれる配列で、1 件以上のエラーオブジェクト（code / message / timestamp / where / phase / stacktrace）が入ります。各フィールドの意味と code に入り得る値は エラーコード一覧 にまとめています。