Event catalogue

Payload shape

Every event is one JSON object:

{
  "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 is the value in the X-RolChat-Event-Id header and is stable across retries. type is <domain>.<noun>.<verb> or <domain>.<verb> in snake_case. data carries the resource as the corresponding GET endpoint would return it, so a receiver can be written against the API reference and never needs a second schema.

Event families

Family	Examples	Emitted when
conversation.*	conversation.created, conversation.assigned, conversation.resolved, conversation.reopened, conversation.merged	A conversation changes state or ownership
message.*	message.created, message.delivered, message.read, message.failed	A message is posted or its delivery status changes
crm.*	crm.lead.created, crm.contact.created, crm.contact.updated, crm.contact.merged, crm.deal.stage_changed, crm.deal.won	A lead, contact, company or deal changes
ticket.*	ticket.created, ticket.status_changed, ticket.assigned, ticket.sla_breached	A ticket changes
visitor.*	visitor.identified, visitor.cobrowse.requested	A visitor is identified or asks for a cobrowse session
marketing.*	marketing.form.submitted, marketing.booking.created, marketing.campaign.sent, marketing.unsubscribed	Forms, bookings, campaigns
kb.*	kb.article.published, kb.article.unpublished	Knowledge base changes
phone.*	phone.call.started, phone.call.ended, phone.call.recorded, phone.call.transcribed, phone.voicemail.received	Calls and voicemail
automation.*	automation.rule.executed, automation.rule.failed	An automation rule runs
privacy.*	privacy.consent.granted, privacy.consent.withdrawn, privacy.dsr.received	Consent and data-subject requests
billing.*	billing.invoice.created, billing.trial_expiring, billing.subscription.changed	Subscription and invoices
auth.*	auth.api_key.created, auth.api_key.revoked, auth.account.swapped	Security-relevant account events
ai.*	ai.usage.recorded	Every AI adapter call, with token counts

The exact list grows with the product; the subscription screen shows every type your account can receive and lets you filter per type.

Subscribing

Webhook subscriptions belong to a plugin. In Settings → Plugins, open the plugin (or create a custom one) and add an endpoint: HTTPS URL, the event types you want, and an optional IP allowlist. The signing secret is shown once. Deliveries, retries and dead letters for that endpoint appear in the plugin’s Webhook log.

The Plugin Protocol on the Plugins page describes how a plugin declares the events it needs in its manifest.

Ordering and delivery

• Delivery is at least once. Deduplicate by id.
• Events for one resource are dispatched in order, but retries can reorder deliveries. Use occurred_at and the resource’s updated_at rather than arrival time.
• A subscription that keeps failing accumulates dead letters; more than 100 for one endpoint raises an alert on RolChat’s side and shows a warning in the plugin’s log.