이벤트 카탈로그

페이로드 형태

모든 이벤트는 하나의 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 어댑터 호출

정확한 목록은 제품과 함께 늘어납니다. 구독 화면에는 계정이 받을 수 있는 모든 유형이 표시되며 유형별로 필터링할 수 있습니다.

구독하기

웹훅 구독은 플러그인에 속합니다. 설정 → 플러그인에서 플러그인을 열고(또는 사용자 지정 플러그인을 만들고) 엔드포인트를 추가합니다: HTTPS URL, 원하는 이벤트 유형, 선택 사항인 IP 허용 목록. 서명 비밀 값은 한 번만 표시됩니다. 해당 엔드포인트의 전송, 재시도, 데드 레터는 플러그인의 웹훅 로그에 나타납니다.

플러그인 페이지의 Plugin Protocol은 플러그인이 매니페스트에서 필요한 이벤트를 선언하는 방법을 설명합니다.

순서와 전송

• 전송은 최소 한 번입니다. id로 중복을 제거하세요.
• 하나의 리소스에 대한 이벤트는 순서대로 발송되지만, 재시도로 인해 전송 순서가 바뀔 수 있습니다. 도착 시간이 아니라 occurred_at과 리소스의 updated_at을 사용하세요.
• 계속 실패하는 구독에는 데드 레터가 쌓입니다. 한 엔드포인트에서 100건을 넘으면 RolChat 쪽에서 경보가 발생하고 플러그인 로그에 경고가 표시됩니다.