Catálogo de eventos

Formato do payload

Todo evento é um objeto 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 é o valor do cabeçalho X-RolChat-Event-Id e permanece o mesmo entre as novas tentativas. type segue o formato <domain>.<noun>.<verb> ou <domain>.<verb> em snake_case. data traz o recurso da mesma forma que o endpoint GET correspondente o retornaria, então um receptor pode ser escrito com base na referência da API e nunca precisa de um segundo schema.

Famílias de eventos

Família	Exemplos	Emitido quando
conversation.*	conversation.created, conversation.assigned, conversation.resolved, conversation.reopened, conversation.merged	Uma conversa muda de estado ou de responsável
message.*	message.created, message.delivered, message.read, message.failed	Uma mensagem é publicada ou seu status de entrega muda
crm.*	crm.lead.created, crm.contact.created, crm.contact.updated, crm.contact.merged, crm.deal.stage_changed, crm.deal.won	Um lead, contato, empresa ou negócio muda
ticket.*	ticket.created, ticket.status_changed, ticket.assigned, ticket.sla_breached	Um ticket muda
visitor.*	visitor.identified, visitor.cobrowse.requested	Um visitante é identificado ou pede uma sessão de cobrowse
marketing.*	marketing.form.submitted, marketing.booking.created, marketing.campaign.sent, marketing.unsubscribed	Formulários, agendamentos, campanhas
kb.*	kb.article.published, kb.article.unpublished	Mudanças na base de conhecimento
phone.*	phone.call.started, phone.call.ended, phone.call.recorded, phone.call.transcribed, phone.voicemail.received	Chamadas e correio de voz
automation.*	automation.rule.executed, automation.rule.failed	Uma regra de automação é executada
privacy.*	privacy.consent.granted, privacy.consent.withdrawn, privacy.dsr.received	Consentimento e solicitações de titulares de dados
billing.*	billing.invoice.created, billing.trial_expiring, billing.subscription.changed	Assinatura e faturas
auth.*	auth.api_key.created, auth.api_key.revoked, auth.account.swapped	Eventos da conta relevantes para a segurança
ai.*	ai.usage.recorded	Toda chamada a um adaptador de IA, com a contagem de tokens

A lista exata cresce junto com o produto; a tela de assinaturas mostra todos os tipos que a sua conta pode receber e permite filtrar por tipo.

Assinando

As assinaturas de webhook pertencem a um plugin. Em Configurações → Plugins, abra o plugin (ou crie um personalizado) e adicione um endpoint: URL HTTPS, os tipos de evento desejados e uma lista opcional de IPs permitidos. O segredo de assinatura é exibido uma única vez. As entregas, as novas tentativas e as dead letters desse endpoint aparecem no Log de webhooks do plugin.

O Plugin Protocol, na página Plugins, descreve como um plugin declara no seu manifesto os eventos de que precisa.

Ordem e entrega

• A entrega é pelo menos uma vez. Elimine duplicados pelo id.
• Os eventos de um mesmo recurso são despachados em ordem, mas as novas tentativas podem alterar a ordem das entregas. Use occurred_at e o updated_at do recurso em vez do horário de chegada.
• Uma assinatura que continua falhando acumula dead letters; mais de 100 para um endpoint geram um alerta do lado do RolChat e mostram um aviso no log do plugin.