API de Chat2Desk OnCloud

Webhooks

Un webhook te envía una solicitud HTTP a tu servidor cada vez que ocurre un evento, para que no tengas que consultar la API cada pocos segundos. Se crean con POST /webhooks: indicas la dirección de tu servidor (se recomienda https), los eventos y, si quieres, los canales.

• Límites: hasta 5 webhooks simultáneos y hasta 24 eventos en cada uno.
• Canales: el campo channels limita los eventos de mensajes y diálogos a ciertos canales; si lo omites, recibes los de todos. Los eventos que no dependen de un canal (operadores, cambios de cliente) llegan siempre.

Reintentos y desactivación

Si tu servidor no responde con éxito, Chat2Desk reintenta:

1. A los 10 segundos.
2. A los 5 minutos.
3. A las 2 horas.

Si pasan 5 horas sin una respuesta exitosa, el webhook se desactiva automáticamente.

Verifica la firma

Cada entrega trae dos encabezados:

Para comprobar que la notificación viene de Chat2Desk y no se alteró:

1. Calcula clave = MD5(tu_token_de_API) y usa su representación hexadecimal de 32 caracteres (no los 16 bytes crudos).
2. Arma el mensaje: cuerpo_crudo_de_la_solicitud seguido del valor de X-Timestamp.
3. Calcula HMAC-SHA256(clave, mensaje) en hexadecimal.
4. Compárala con X-Signature usando una comparación en tiempo constante, no un ==.
5. Si no coinciden, rechaza la notificación.

El error más común es el cuerpo. Firma los bytes exactos que envió Chat2Desk, antes de que tu framework los convierta a JSON. Si el cuerpo se reformatea (otro orden de llaves u otros espacios), la firma no coincidirá aunque el contenido parezca igual.

Python

import hashlib
import hmac

def firma_valida(token_api: str, cuerpo_crudo: bytes, x_timestamp: str, x_signature: str) -> bool:
    clave = hashlib.md5(token_api.encode()).hexdigest()  # 32 caracteres hexadecimales
    mensaje = cuerpo_crudo + x_timestamp.encode()
    esperada = hmac.new(clave.encode(), mensaje, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, x_signature)

Node.js

const crypto = require('crypto');

// cuerpoCrudo: Buffer con los bytes exactos recibidos, antes de JSON.parse
function firmaValida(tokenApi, cuerpoCrudo, xTimestamp, xSignature) {
  const clave = crypto.createHash('md5').update(tokenApi).digest('hex');
  const mensaje = Buffer.concat([cuerpoCrudo, Buffer.from(xTimestamp)]);
  const esperada = crypto.createHmac('sha256', clave).update(mensaje).digest('hex');
  const a = Buffer.from(esperada);
  const b = Buffer.from(xSignature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Eventos disponibles

Estos son los 24 eventos que puedes pedir en el campo events:

Usa estos nombres exactamente al suscribirte. Para operator_status_changed, device_updated y new_ticket, los nombres más nuevos que aparecen en algunos materiales (operator_status_updated, device_update, ticket_created) se rechazan en la API de producción.

Cada entrega incluye el tipo de evento en hook_type, la hora en event_time y los datos del mensaje o del objeto. Por ejemplo, un inbox trae message_id, type, text, transport, client_id, dialog_id, channel_id, el objeto client, request_id, attachments, is_new_request e is_new_client.