Catalogo degli eventi

Struttura del payload

Ogni evento è un unico oggetto 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 è il valore dell’intestazione X-RolChat-Event-Id e resta stabile tra i tentativi. type ha la forma <domain>.<noun>.<verb> oppure <domain>.<verb> in snake_case. data contiene la risorsa così come la restituirebbe l’endpoint GET corrispondente, quindi un ricevitore si può scrivere basandosi sul riferimento API senza mai bisogno di un secondo schema.

Famiglie di eventi

Famiglia	Esempi	Emesso quando
conversation.*	conversation.created, conversation.assigned, conversation.resolved, conversation.reopened, conversation.merged	Una conversazione cambia stato o assegnatario
message.*	message.created, message.delivered, message.read, message.failed	Un messaggio viene pubblicato o cambia il suo stato di consegna
crm.*	crm.lead.created, crm.contact.created, crm.contact.updated, crm.contact.merged, crm.deal.stage_changed, crm.deal.won	Cambia un lead, un contatto, un’azienda o un deal
ticket.*	ticket.created, ticket.status_changed, ticket.assigned, ticket.sla_breached	Cambia un ticket
visitor.*	visitor.identified, visitor.cobrowse.requested	Un visitatore viene identificato o chiede una sessione di cobrowse
marketing.*	marketing.form.submitted, marketing.booking.created, marketing.campaign.sent, marketing.unsubscribed	Moduli, prenotazioni, campagne
kb.*	kb.article.published, kb.article.unpublished	Modifiche alla base di conoscenza
phone.*	phone.call.started, phone.call.ended, phone.call.recorded, phone.call.transcribed, phone.voicemail.received	Chiamate e segreteria
automation.*	automation.rule.executed, automation.rule.failed	Viene eseguita una regola di automazione
privacy.*	privacy.consent.granted, privacy.consent.withdrawn, privacy.dsr.received	Consensi e richieste degli interessati
billing.*	billing.invoice.created, billing.trial_expiring, billing.subscription.changed	Abbonamento e fatture
auth.*	auth.api_key.created, auth.api_key.revoked, auth.account.swapped	Eventi dell’account rilevanti per la sicurezza
ai.*	ai.usage.recorded	Ogni chiamata a un adattatore AI, con il conteggio dei token

L’elenco esatto cresce con il prodotto; la schermata delle iscrizioni mostra ogni tipo che il tuo account può ricevere e permette di filtrare per tipo.

Iscrizione

Le iscrizioni ai webhook appartengono a un plugin. In Impostazioni → Plugin, apri il plugin (o creane uno personalizzato) e aggiungi un endpoint: URL HTTPS, i tipi di evento che ti interessano e una allowlist di IP facoltativa. Il segreto di firma viene mostrato una sola volta. Consegne, nuovi tentativi e dead letter di quell’endpoint compaiono nel Log dei webhook del plugin.

Il Plugin Protocol nella pagina Plugin descrive come un plugin dichiara nel proprio manifest gli eventi di cui ha bisogno.

Ordine e consegna

• La consegna è almeno una volta. Deduplica in base a id.
• Gli eventi di una stessa risorsa vengono inviati in ordine, ma i nuovi tentativi possono alterare l’ordine delle consegne. Usa occurred_at e updated_at della risorsa invece dell’orario di arrivo.
• Un’iscrizione che continua a fallire accumula dead letter; oltre 100 per un endpoint fanno scattare un avviso lato RolChat e mostrano un’allerta nel log del plugin.