Apartado 5 de 15 · Sincronizar
Webhooks: que Chatendo te avise
Da de alta un webhook en Chatendo, los 45 eventos que envía, cómo comprobar la firma X-Vertichat-Signature y cómo ponerte al día si tu servidor no contesta.
En esta página (4)
5.1 · Dar de alta el aviso
Necesita el permiso webhooks:manage.
curl -s -X POST "$API/webhook-endpoints" \
-H "Authorization: Bearer $TOKEN" \
-H 'Accept: application/json' -H 'Content-Type: application/json' \
-d '{"url":"https://tu-servidor.example/chatendo",
"events":["message.received","conversation.assigned"]}'Respuesta (la forma, probada el 22-09-2026; el secreto, recortado y de ejemplo):
{"id":1,
"url":"https://tu-servidor.example/chatendo",
"events":["message.received","conversation.assigned"],
"active":true,
"created_at":"2026-09-22T17:18:24Z",
"signing_secret":"a1b2c3d4…"}Ese signing_secret es lo único que verás una vez. Guárdalo: sin él no puedes comprobar la firma, y sin comprobar la firma cualquiera puede llamar a tu URL fingiendo ser Chatendo.
La URL tiene que ser pública. Hay guardia anti-SSRF: una dirección interna o de red privada se rechaza con 422 SSRF_BLOCKED. Para desarrollo, usa un túnel público.
5.2 · Los eventos
Son 45 de uso general (la lista viva puede traer alguno más, de apps que aún no están abiertas). La lista viva, con la descripción de cada uno, la da GET /webhook-endpoints/events (o /eventos; mismo permiso webhooks:manage). Te puedes suscribir a uno por uno o a un grupo entero con grupo.* (por ejemplo contact.*); * a secas no se acepta. Los del embudo, las tareas, las empresas, la captación, el catálogo y los presupuestos solo salen con su app encendida en la cuenta.
| Evento | Cuándo sale |
|---|---|
contact.created |
Se ha creado un contacto: por un mensaje entrante, a mano, por la API o por una importación. También cuando uno borrado vuelve de la papelera (data.restored = true, el mismo contact.id). |
contact.updated |
Ha cambiado algún dato del contacto (nombre, teléfono, baja…). Sale una vez por guardado; data.changes dice qué campos. |
contact.merged |
Dos contactos se han fusionado: data.contact es el que queda y data.merged_contact el que desaparece. |
contact.deleted |
Se ha borrado un contacto (a mano, por RGPD o por quedar absorbido en una fusión). |
contact.tags_changed |
Han cambiado las etiquetas del contacto: las que tiene ahora, las añadidas y las quitadas. |
conversation.created |
Se ha abierto una conversación nueva con un contacto. |
conversation.assigned |
La conversación se ha asignado (o reasignado) a una persona del equipo. |
conversation.closed |
La conversación se ha cerrado. |
conversation.reopened |
Una conversación cerrada se ha vuelto a abrir, a mano o porque el cliente ha vuelto a escribir. |
conversation.snoozed |
La conversación se ha pospuesto hasta una fecha (data.snoozed_until). |
conversation.unsnoozed |
Una conversación pospuesta ha vuelto a la bandeja: a mano, por vencer el plazo o porque el cliente ha vuelto a escribir o llamar. |
conversation.tags_changed |
Han cambiado las etiquetas de la conversación: las que tiene ahora, las añadidas y las quitadas. |
message.received |
Ha entrado un mensaje del cliente. |
message.sent |
Ha salido un mensaje hacia el cliente (lo mandó una persona, la IA, una campaña o la API). |
message.delivered |
Meta confirma que un mensaje saliente ha llegado al teléfono del cliente. |
message.read |
Meta confirma que el cliente ha leído un mensaje saliente. |
message.failed |
Un mensaje saliente no ha podido entregarse; data.message.error lleva el motivo de Meta. |
message.status_updated |
Obsoleto, se mantiene por compatibilidad: cualquier cambio de estado de un mensaje saliente. Usa message.delivered, message.read y message.failed. |
appointment.created |
Se ha reservado una cita en la agenda. |
appointment.updated |
Ha cambiado una cita: nueva hora, invitado o notas. |
appointment.cancelled |
Se ha anulado una cita. |
channel.health_changed |
Meta ha cambiado lo que deja hacer al canal (AVAILABLE, LIMITED, BLOCKED): lleva el estado anterior y el nuevo. |
template.status_changed |
Meta ha cambiado el estado de una plantilla (aprobada, rechazada, en pausa…): lleva el anterior y el nuevo. |
campaign.finished |
Una campaña ha terminado de enviar a todos sus destinatarios. |
payment.completed |
Un cobro pendiente ha quedado pagado, por Stripe o marcado a mano. |
order.created |
Ha llegado un pedido nuevo de la tienda enlazada. |
opportunity.created |
Se ha creado una oportunidad (app «Embudo de ventas»). |
opportunity.stage_changed |
Una oportunidad abierta ha cambiado de etapa, la mueva quien la mueva. |
opportunity.won |
Una oportunidad se ha ganado; lleva el importe final y la fecha. |
opportunity.lost |
Una oportunidad se ha perdido; lleva el motivo (null si la cerró el seguimiento por etapa). |
task.created |
Se ha creado una tarea (app «Tareas»). |
task.completed |
Una tarea se ha completado; lleva el resultado. |
task.overdue |
Una tarea pendiente ha pasado su vencimiento sin hacerse. Sale una vez por tarea y vencimiento; una tarea en estado «Detenido» no lo emite. |
company.created |
Se ha creado una empresa (app «Empresas»). |
company.updated |
Ha cambiado algún dato de la empresa, sus etiquetas, sus campos propios o sus personas (data.changes dice qué). |
lead.captured |
Ha entrado un lead (formulario web o Lead Ads de Meta) y ya tiene contacto (app «Captación»). Chatendo no le escribe nada al lead. |
product.created |
Se ha dado de alta un producto o servicio en el catálogo (app «Catálogo»). |
product.updated |
Ha cambiado un producto del catálogo (data.changes dice qué); también al archivarlo o restaurarlo. |
quote.created |
Se ha hecho un presupuesto nuevo, en borrador (app «Presupuestos»). |
quote.sent |
Se ha emitido un presupuesto (tiene número y su enlace funciona); data.via dice cómo salió. |
quote.viewed |
El cliente ha abierto el presupuesto por primera vez desde su enlace. |
quote.accepted |
El cliente ha aceptado el presupuesto desde su enlace. |
quote.rejected |
El cliente ha rechazado el presupuesto desde su enlace (con su motivo, si lo dio). |
quote.expired |
Ha pasado la fecha de validez de un presupuesto enviado sin respuesta. |
privacy.erasure_completed |
Se ha suprimido a una persona (derecho de supresión). Borra tu copia de contact_id y de cada id de absorbed_contact_ids. |
Los eventos del embudo, las tareas, las empresas, la captación, el catálogo y los presupuestos solo salen con su app encendida en la cuenta.
Las tareas (§14.3) tienen su apartado con el cuerpo.
El sobre. Todos los avisos llevan el mismo sobre, y el diario de eventos (GET /events, §5.4) sirve el mismo: event_id (evt_ y 26 caracteres, el mismo en todos los endpoints y en todos los reintentos del mismo hecho: úsalo para descartar duplicados), type, occurred_at (el instante del hecho, no el del intento), tenant_id, data y actor (quién lo provocó: kind es user, ai, api o system, e id el de la persona o el dueño del token, o null). Siguen yendo también id y event, los nombres de la primera versión (id = event_id, event = type): se mantienen por compatibilidad y están obsoletos.
Cuerpo de message.received. Los campos son los que manda Chatendo, uno por uno; los valores son de ejemplo:
{"event_id": "evt_01J8Z3K4Q7M2X9V5N6B8C1D0EF",
"type": "message.received",
"occurred_at": "2026-09-22T17:02:05Z",
"tenant_id": 4,
"data": {"id": 86934,
"wamid": "wamid.HBg…",
"direction": "in",
"type": "text",
"body": "¿Seguís teniendo plaza?",
"conversation_id": 2856,
"contact_id": 41,
"created_at": "2026-09-22T17:02:05Z",
"contact": {"id": 41, "external_id": null, "phone_e164": "+34600111222", "name": "Ana López"},
"conversation": {"id": 2856, "external_id": null, "status": "open", "channel_id": 12}},
"actor": {"kind": "system", "id": null},
"id": "evt_01J8Z3K4Q7M2X9V5N6B8C1D0EF",
"event": "message.received"}El contacto y la conversación ya vienen dentro. Todos los eventos de contactos, conversaciones y mensajes traen en data el bloque contact (id, external_id, phone_e164, name, y email en los contactos de correo, que no tienen teléfono) y el bloque conversation (id, external_id, status, channel_id), así que no hace falta dar otra vuelta a GET /contacts/{id} por cada aviso. Los campos de arriba que ya traía message.received desde el principio (id, wamid, conversation_id…) siguen donde estaban.
5.3 · Comprobar la firma
Cada entrega lleva estas cabeceras:
X-Vertichat-Signature: sha256=<hmac-sha256 del cuerpo crudo, con tu signing_secret>
X-Vertichat-Event: message.received
X-Vertichat-Event-Id: evt_01J8Z3K4Q7M2X9V5N6B8C1D0EF
X-Vertichat-Delivery: 18342
X-Vertichat-Timestamp: 1790000000Event-Id es el event_id del cuerpo, Delivery el número de esa entrega (el mismo aunque se reenvíe) y Timestamp la hora del intento en segundos Unix. Las cabeceras conservan el nombre viejo del producto. Es un identificador, no una errata.
import hmac, hashlib
def firma_valida(cuerpo_crudo: bytes, cabecera: str, secreto: str) -> bool:
esperada = 'sha256=' + hmac.new(
secreto.encode(), cuerpo_crudo, hashlib.sha256
).hexdigest()
return hmac.compare_digest(esperada, cabecera or '')Dos reglas que no son opcionales:
- Sobre el cuerpo SIN parsear. Si lo deserializas y lo vuelves a serializar, un espacio distinto rompe la firma y te pasarás la tarde buscando el fallo donde no está.
- Comparación en tiempo constante (
compare_digest), nunca==.
5.4 · Contestar rápido
Chatendo espera 10 segundos tu respuesta. Hasta 5 intentos: el primero al momento y, si no contestas con un 2xx, otros a los 5 segundos, 30 segundos, 5 minutos y 30 minutos. Tras el quinto, la entrega queda en failed.
Devuelve 2xx en cuanto recibas y haz el trabajo después, en una cola tuya. Si procesas antes de contestar y tardas, Chatendo reintenta y te llega el mismo evento otra vez.
Las entregas se consultan en GET /webhook-endpoints/{id}/deliveries, y esa ruta pide webhooks:manage como las demás — devuelve los payloads ya enviados, con teléfonos y textos de clientes dentro. Cambió el 22-09-2026: hasta ese día era la única de las cinco que no lo pedía, y cualquier token del inquilino la leía. Si tu token es anterior y no tiene ese permiso, ahora recibirás 403.
Si tu servidor estuvo caído, no pierdes nada. Hay tres maneras de ponerte al día, con webhooks:manage (y rol de propietario o administrador en la persona que creó el token):
- Reenviar una entrega fallida:
POST /webhook-endpoints/{id}/deliveries/{entrega}/retry. La entrega vuelve apending, con los 5 intentos otra vez, el mismo cuerpo, la misma firma y el mismoevent_id. Si no estaba enfailed:409 DELIVERY_NOT_RETRYABLE. - Reenviar todas las fallidas de una ventana:
POST /webhook-endpoints/{id}/deliveries/retry-failedconsince(obligatorio) yuntil. Encola hasta 500 por llamada y contesta202 {"queued", "capped", "remaining"}; sicappedestrue, repite la llamada. Con el endpoint apagado:409 ENDPOINT_INACTIVE. - Preguntar qué te perdiste:
GET /events?since=…(permisoevents:read) devuelve el diario de eventos de los últimos 7 días, con el mismo sobre que los avisos, en orden deoccurred_at. Admitetypes(tipos separados por comas),per_page(hasta 500, 100 de serie) ycursor: sigue con elmeta.next_cursorque te devuelve hasta quemeta.has_moreseafalse, y guárdalo para la vez siguiente. No sirve nada de los últimos 5 segundos (meta.settle_seconds), para que el cursor nunca pase por delante de un evento que aún no se ve. Un cursor con otros filtros da422 INVALID_CURSOR.
Las entregas de GET /webhook-endpoints/{id}/deliveries se filtran con status, event_type, since y until, y se pasan por cursor (per_page hasta 100).