イベントカタログ

ペイロードの形式

すべてのイベントは1つの JSON オブジェクトです。

{
  "id": "evt_01HKQN9…",
  "type": "conversation.created",
  "occurred_at": "2026-04-20T14:23:45.123Z",
  "account_id": "7c1d2c6e-…",
  "site_id": "0f3a…",
  "data": { … the resource, in the same shape the API returns it … }
}

id は X-RolChat-Event-Id ヘッダーの値で、再試行をまたいで変わりません。type は snake_case の <domain>.<noun>.<verb> または <domain>.<verb> です。data には対応する GET エンドポイントが返すのと同じ形式でリソースが含まれるため、受信側は API リファレンスに沿って実装でき、別のスキーマを用意する必要はありません。

イベントファミリー

ファミリー	例	送信されるタイミング
`conversation.*`	`conversation.created`、`conversation.assigned`、`conversation.resolved`、`conversation.reopened`、`conversation.merged`	会話の状態または担当が変わったとき
`message.*`	`message.created`、`message.delivered`、`message.read`、`message.failed`	メッセージが投稿された、または配信状況が変わったとき
`crm.*`	`crm.lead.created`、`crm.contact.created`、`crm.contact.updated`、`crm.contact.merged`、`crm.deal.stage_changed`、`crm.deal.won`	リード、連絡先、企業、商談が変わったとき
`ticket.*`	`ticket.created`、`ticket.status_changed`、`ticket.assigned`、`ticket.sla_breached`	チケットが変わったとき
`visitor.*`	`visitor.identified`、`visitor.cobrowse.requested`	訪問者が識別された、または共同ブラウジングのセッションを求めたとき
`marketing.*`	`marketing.form.submitted`、`marketing.booking.created`、`marketing.campaign.sent`、`marketing.unsubscribed`	フォーム、予約、キャンペーン
`kb.*`	`kb.article.published`、`kb.article.unpublished`	ナレッジベースの変更
`phone.*`	`phone.call.started`、`phone.call.ended`、`phone.call.recorded`、`phone.call.transcribed`、`phone.voicemail.received`	通話とボイスメール
`automation.*`	`automation.rule.executed`、`automation.rule.failed`	自動化ルールが実行されたとき
`privacy.*`	`privacy.consent.granted`、`privacy.consent.withdrawn`、`privacy.dsr.received`	同意とデータ主体からの請求
`billing.*`	`billing.invoice.created`、`billing.trial_expiring`、`billing.subscription.changed`	サブスクリプションと請求書
`auth.*`	`auth.api_key.created`、`auth.api_key.revoked`、`auth.account.swapped`	セキュリティに関わるアカウントのイベント
`ai.*`	`ai.usage.recorded`	AI アダプターへのすべての呼び出し（トークン数付き）

正確な一覧は製品とともに増えていきます。購読の画面には、アカウントが受け取れるすべてのタイプが表示され、タイプごとに絞り込めます。

購読する

Webhook の購読はプラグインに属します。設定 → プラグイン でプラグインを開き（またはカスタムプラグインを作成し）、エンドポイントを追加します: HTTPS の URL、受け取りたいイベントタイプ、任意の IP 許可リスト。署名用のシークレットは一度だけ表示されます。そのエンドポイントの配信、再試行、デッドレターは、プラグインの Webhook ログに表示されます。

プラグインのページにある Plugin Protocol では、プラグインが必要なイベントをマニフェストで宣言する方法を説明しています。

順序と配信

配信は少なくとも1回です。id で重複を排除してください。
1つのリソースに関するイベントは順番に送信されますが、再試行によって配信の順序が入れ替わることがあります。到着時刻ではなく、occurred_at とリソースの updated_at を使ってください。
失敗し続ける購読にはデッドレターが蓄積されます。1つのエンドポイントで100件を超えると RolChat 側でアラートが発生し、プラグインのログに警告が表示されます。