Eventos de webhook
CustomerHero entrega eventos a tus endpoints mediante POSTs firmados. Esta página lista todos los tipos de evento a los que puedes suscribirte. El esquema de firma, la política de reintentos y las cabeceras HTTP están documentados en la referencia de la API.
Suscribirse
Crea una suscripción en Ajustes → Webhooks → Nueva suscripción. Elige los tipos de evento, la URL de destino y un secreto HMAC (autogenerado por defecto). También puedes suscribirte mediante la API.
Usa * para suscribirte a todos los eventos que emita la org, incluyendo los futuros. Nunca eliminamos un tipo de evento sin un periodo de deprecación, pero si prefieres optar deliberadamente, lista cada evento que te interese.
Catálogo de eventos
Conversación
| Evento | Descripción |
|---|---|
| conversation.created | Empieza una conversación nueva en cualquier canal. |
| conversation.updated | Cambian campos de primer nivel de una conversación (asunto, cliente, etc.). |
| conversation.tagged | Se añadió o quitó una etiqueta. |
| conversation.assigned | Cambió la asignación (usuario o equipo). |
| conversation.status_changed | El estado pasó entre abierta / pendiente / cerrada. |
| conversation.closed | Evento de conveniencia: se dispara junto a conversation.status_changed cuando el estado pasa a cerrada. |
| conversation.rated | El cliente dejó una valoración CSAT. |
| csat.low_score | Evento de conveniencia: se dispara cuando una valoración CSAT es negativa. |
Mensaje
| Evento | Descripción |
|---|---|
| message.created | Cualquier mensaje nuevo en cualquier conversación. Si solo te interesa uno u otro rol, usa los eventos específicos. |
| message.created_by_user | Mensaje entrante del cliente final. |
| message.created_by_assistant | Mensaje saliente generado por la IA. |
| message.created_by_agent | Mensaje saliente enviado por un agente humano. |
Cliente
| Evento | Descripción |
|---|---|
| customer.created | Se creó un nuevo registro de cliente. |
| customer.updated | Cambiaron campos de primer nivel del cliente (nombre, email, teléfono). |
| customer.property_updated | Cambió una propiedad personalizada del cliente. |
| customer.merged | Se fusionaron dos registros de clientes. El payload incluye ambos ids. |
Reserva
| Evento | Descripción |
|---|---|
| booking.created | Se creó una cita a través de un flujo de reservas del chatbot. |
| booking.cancelled | Se canceló una cita ya creada. |
Operativo
| Evento | Descripción |
|---|---|
| handoff.triggered | El bot pasó la conversación a un humano (toma manual, regla de escalado o salvaguarda). |
| guardrail.tripped | Una respuesta fue bloqueada o reescrita por una salvaguarda de contenido o PII. |
Forma del payload
Todos los eventos comparten el mismo sobre. El campo data contiene el recurso que cambió; en eventos *.updated y *.tagged, un campo previous muestra los valores anteriores de los campos que cambiaron.
{
"id": "evt_01h9k4...",
"type": "conversation.assigned",
"apiVersion": "v1",
"createdAt": "2026-05-09T14:22:01.882Z",
"orgId": "org_k7x9...",
"data": {
"conversation": {
"id": "cnv_b3a8...",
"status": "open",
"assignee": {
"id": "usr_5nf2...",
"name": "Carlos Pérez"
},
"customer": {
"id": "cus_q1k0...",
"email": "jane@acme.com"
}
}
},
"previous": {
"assignee": null
}
}Reintentos y orden
Una entrega se considera exitosa con cualquier respuesta 2xx. Cualquier otra cosa (incluido 429, 5xx y errores de red) dispara reintentos con retroceso exponencial durante hasta 24 horas. Pasado ese plazo la entrega se marca como fallida y aparece en Ajustes → Webhooks → Actividad para que puedas reenviarla manualmente.
Los eventos no están garantizados a llegar en orden. Usa el campo createdAt del sobre como timestamp canónico y deduplica con el campo id (también disponible en la cabecera Idempotency-Key). El mismo id de evento nunca apuntará a un payload distinto.
Próximos pasos
Mira los ejemplos de verificación HMAC en la referencia de la API → Webhooks.