Webhook API - Comdesk ヘルプ

ベース URL：https://xxxx.comdesk.com/api/v1

Webhook 管理は open_api_advanced ライセンスと、webhooks:manage スコープを持つキーが必要です。イベントペイロード、署名検証、再送、自動無効化は Webhook ガイドを参照してください。

メソッド	パス	スコープ
`POST`	`/webhooks`	`webhooks:manage`
`GET`	`/webhooks`	`webhooks:manage`
`GET`	`/webhooks/{webhookId}`	`webhooks:manage`
`PUT`	`/webhooks/{webhookId}`	`webhooks:manage`
`DELETE`	`/webhooks/{webhookId}`	`webhooks:manage`
`POST`	`/webhooks/{webhookId}/test`	`webhooks:manage`

Webhook オブジェクト

integer

string

説明的な名前、または null。

string

識別用の、署名シークレットの先頭 12 文字。

array

購読しているイベント種別。

object

登録済みのフィルター、または null。配信時にはまだ適用されません。

boolean

配信が行われるかどうか。

string

最後に配信に成功した日時（ISO 8601）、または null。

integer

配信試行の連続失敗回数（再送を含む）。1 回でも成功すると 0 にリセットされ、10 に達すると Webhook は自動的に無効化されます。

string

Webhook を登録する

POST /webhooks

ボディ

string

required

POST 配信を受信するエンドポイント、最大 2,048 文字。https:// を使用し、パブリックなアドレスに解決される必要があります（プライベート／内部ホストは拒否されます）。それ以外は 422。

array

required

call.started、call.completed、call.missed、call.voicemail、call.failed、customer.created、customer.updated、transcription.completed、summary.completed、ivr.trigger のうち 1 つ以上。Webhook ガイドの「イベント」を参照してください — call.failed と ivr.trigger にはまだ発生元がありません。

string

説明的な名前、最大 255 文字。

boolean

default:"true"

Webhook が有効かどうか。

object

任意の project_ids（整数の配列）と call_status（文字列の配列、例：["missed_call", "no_answer"]）。それ以外のキーは拒否されます。

curl -X POST https://xxxx.comdesk.com/api/v1/webhooks \
  -H "Authorization: Bearer $COMDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack notifications",
    "url": "https://hooks.example.com/comdesk",
    "events": ["call.missed", "call.completed"],
    "is_active": true
  }'

201 レスポンスは、Webhook オブジェクトに secret（X-Comdesk-Signature に使われる署名シークレット）を加えたものです。シークレットが返されるのはここだけです。すぐに保存してください。

{
  "data": {
    "id": 1,
    "name": "Slack notifications",
    "url": "https://hooks.example.com/comdesk",
    "secret": "whsec_…",
    "secret_prefix": "whsec_ab12cd",
    "events": ["call.missed", "call.completed"],
    "filters": null,
    "is_active": true,
    "created_at": "2026-07-15T18:40:00+09:00",
    "message": "Store this secret now. It cannot be retrieved later."
  }
}

Webhook 一覧

GET /webhooks テナントのすべての Webhook を、Webhook オブジェクト（上記「Webhook オブジェクト」を参照）の配列として返します。

Webhook の取得

GET /webhooks/{webhookId} 1 件の Webhook オブジェクト（上記「Webhook オブジェクト」を参照）を返します。存在しない場合は 404 resource_not_found を返します。

Webhook の更新

PUT /webhooks/{webhookId} 登録と同じルールで name、url、events、is_active、filters を受け付けます。変更分のみ送信してください。更新後の Webhook オブジェクト（上記「Webhook オブジェクト」を参照）を返します。自動無効化された Webhook を再度有効化するには {"is_active": true} を使用します。シークレットは変更できません — ローテーションするには、Webhook を削除して再登録してください。

Webhook の削除

DELETE /webhooks/{webhookId} Webhook を削除します。配信は即時に停止します。204 No Content を返します。

Webhook のテスト

POST /webhooks/{webhookId}/test 署名付きの webhook.test イベントを設定済み URL に同期的に送信し（タイムアウト 5 秒、再送なし）、結果を返します。接続性と署名検証の確認に使用してください。テストペイロードは次のとおりです：

{
  "event": "webhook.test",
  "event_id": "…",
  "timestamp": "2026-07-15T18:47:14+09:00",
  "data": { "webhook_id": 1, "message": "This is a test event from Comdesk." }
}

boolean

エンドポイントが 2xx を返した場合は true。

integer

エンドポイントが返した HTTP ステータス。応答がない場合は null。

integer

往復時間（ミリ秒）。

string

応答があった場合は null。それ以外は timeout、connection、blocked（パブリックアドレスのチェックで URL が拒否された）、または unknown。

string

応答を受信できなかった場合のみ含まれます。

{
  "data": {
    "success": true,
    "status_code": 200,
    "latency_ms": 142,
    "error_type": null
  }
}