Saltar al contenido

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.

Revisado el API 1.158.0 8 min de lectura

En esta página (4)
  1. 5.1 · Dar de alta el aviso
  2. 5.2 · Los eventos
  3. 5.3 · Comprobar la firma
  4. 5.4 · Contestar rápido

5.1 · Dar de alta el aviso

Necesita el permiso webhooks:manage.

Terminal
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):

JSON
{"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:

JSON
{"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:

Texto
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: 1790000000

Event-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.

Python
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:

  1. 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á.
  2. 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 a pending, con los 5 intentos otra vez, el mismo cuerpo, la misma firma y el mismo event_id. Si no estaba en failed: 409 DELIVERY_NOT_RETRYABLE.
  • Reenviar todas las fallidas de una ventana: POST /webhook-endpoints/{id}/deliveries/retry-failed con since (obligatorio) y until. Encola hasta 500 por llamada y contesta 202 {"queued", "capped", "remaining"}; si capped es true, repite la llamada. Con el endpoint apagado: 409 ENDPOINT_INACTIVE.
  • Preguntar qué te perdiste: GET /events?since=… (permiso events:read) devuelve el diario de eventos de los últimos 7 días, con el mismo sobre que los avisos, en orden de occurred_at. Admite types (tipos separados por comas), per_page (hasta 500, 100 de serie) y cursor: sigue con el meta.next_cursor que te devuelve hasta que meta.has_more sea false, 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 da 422 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).

Escríbenos por WhatsApp Te contesta nuestro agente de IA al momento