Catálogo de eventos

Forma del contenido

Cada evento es un 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 es el valor de la cabecera X-RolChat-Event-Id y se mantiene estable entre reintentos. type es <domain>.<noun>.<verb> o <domain>.<verb> en snake_case. data contiene el recurso tal como lo devolvería el endpoint GET correspondiente, así que un receptor se puede escribir a partir de la referencia de la API sin necesitar un segundo esquema.

Familias de eventos

Familia	Ejemplos	Se emite cuando
conversation.*	conversation.created, conversation.assigned, conversation.resolved, conversation.reopened, conversation.merged	Una conversación cambia de estado o de responsable
message.*	message.created, message.delivered, message.read, message.failed	Se publica un mensaje o cambia su estado de entrega
crm.*	crm.lead.created, crm.contact.created, crm.contact.updated, crm.contact.merged, crm.deal.stage_changed, crm.deal.won	Cambia un lead, un contacto, una empresa o una oportunidad
ticket.*	ticket.created, ticket.status_changed, ticket.assigned, ticket.sla_breached	Cambia un ticket
visitor.*	visitor.identified, visitor.cobrowse.requested	Se identifica a un visitante o pide una sesión de navegación conjunta
marketing.*	marketing.form.submitted, marketing.booking.created, marketing.campaign.sent, marketing.unsubscribed	Formularios, reservas, campañas
kb.*	kb.article.published, kb.article.unpublished	Cambios en la base de conocimiento
phone.*	phone.call.started, phone.call.ended, phone.call.recorded, phone.call.transcribed, phone.voicemail.received	Llamadas y buzón de voz
automation.*	automation.rule.executed, automation.rule.failed	Se ejecuta una regla de automatización
privacy.*	privacy.consent.granted, privacy.consent.withdrawn, privacy.dsr.received	Consentimiento y solicitudes de los interesados
billing.*	billing.invoice.created, billing.trial_expiring, billing.subscription.changed	Suscripción y facturas
auth.*	auth.api_key.created, auth.api_key.revoked, auth.account.swapped	Eventos de la cuenta relevantes para la seguridad
ai.*	ai.usage.recorded	Cada llamada a un adaptador de IA, con el recuento de tokens

La lista exacta crece con el producto; la pantalla de suscripción muestra todos los tipos que puede recibir tu cuenta y te permite filtrar por tipo.

Suscribirse

Las suscripciones a webhooks pertenecen a un plugin. En Configuración → Plugins, abre el plugin (o crea uno personalizado) y añade un endpoint: URL HTTPS, los tipos de evento que quieres y, opcionalmente, una lista de IP permitidas. El secreto de firma se muestra una vez. Los envíos, los reintentos y los mensajes fallidos de ese endpoint aparecen en el Registro de webhooks del plugin.

El Plugin Protocol de la página Plugins describe cómo declara un plugin en su manifiesto los eventos que necesita.

Orden y entrega

• La entrega es al menos una vez. Deduplica por id.
• Los eventos de un recurso se envían en orden, pero los reintentos pueden alterar el orden de llegada. Usa occurred_at y el updated_at del recurso en lugar de la hora de llegada.
• Una suscripción que falla continuamente acumula mensajes fallidos; más de 100 para un endpoint generan una alerta en RolChat y muestran un aviso en el registro del plugin.