Descripción general de Webhooks

​

Introducción a los Webhooks

​

Cómo Funcionan los Webhooks

1. Configura tu Endpoint
   Configura la URL del webhook en la plataforma de Altur. Esta URL recibirá las solicitudes POST cuando se dispare un evento.
2. Recibe Notificaciones
   Cuando ocurre un evento, Altur envía un POST con los detalles del evento en formato JSON a tu endpoint.
3. Confirma la Recepción
   Tu endpoint debe responder con un código 200 OK para confirmar la recepción. Altur espera hasta 5 segundos por la respuesta. Los timeouts, errores de conexión y respuestas 5xx, 408 y 429 se reintentan con backoff exponencial (hasta 5 intentos en total). Cualquier otra respuesta 4xx falla de inmediato sin reintentos, y los redirects no se siguen. Consulta la sección Política de Reintentos más abajo.

​

Tipos de Evento

• on_call_end: Se dispara al final de una llamada. Envía información detallada de la llamada junto con datos básicos del agente de IA y del usuario final.
• transfer_started: Se dispara cuando inicia una transferencia, para preparar contexto en tiempo real para tus agentes humanos.
• transfer_completed: Se dispara cuando conecta la transferencia con el agente humano.
• campaign.status_changed: Se dispara cuando una Campaña cambia de estado. Incluye el snapshot de analíticas cuando la campaña llega a finished.
• campaign.cycle_completed: Se dispara cuando una iteración del ciclo de una Campaña termina, con el número de iteración completada y el timestamp de la siguiente iteración.

​

Asegurando tus Webhooks

​

Cómo Funciona

• Secreto Compartido: Cada integración de webhook se configura con una llave secreta única codificada en base64.
• Generación del HMAC: Altur genera un hash HMAC SHA-256 usando el secreto compartido (decodificado de base64) y el payload serializado como JSON compacto (sin espacios después de : ni ,, con los caracteres no ASCII escapados como \uXXXX, p. ej. Sofía → Sof\u00eda). El hash se codifica en base64 y se incluye en el header X-Altur-Signature.
• Validación: Tu endpoint debe parsear el body y volver a serializarlo en ese mismo formato compacto antes de calcular el HMAC.

​

Función de Validación de Ejemplo

import base64
import hashlib
import hmac
import json


def is_valid_signature(secret: str, payload: dict, signature: str) -> bool:
    """
    Valida la firma de un webhook de Altur.

    Args:
        secret: Llave secreta compartida codificada en base64
        payload: Body de la solicitud ya parseado (no el body crudo)
        signature: Firma codificada en base64 del header X-Altur-Signature
    """
    # Volver a serializar en formato compacto. json.dumps escapa los
    # caracteres no ASCII como \uXXXX por defecto, igual que Altur.
    payload_bytes = json.dumps(payload, separators=(",", ":")).encode("utf-8")

    # Decodificar el secreto base64
    secret_bytes = base64.b64decode(secret)

    # Generar la firma esperada
    expected_signature = base64.b64encode(
        hmac.new(secret_bytes, payload_bytes, hashlib.sha256).digest()
    ).decode()

    return hmac.compare_digest(signature, expected_signature)

const crypto = require("crypto");

function isValidSignature(secret, payload, signature) {
  /**
   * Valida la firma de un webhook de Altur.
   *
   * @param {string} secret - Llave secreta compartida codificada en base64
   * @param {object} payload - Body de la solicitud ya parseado (no el body crudo)
   * @param {string} signature - Firma codificada en base64 del header X-Altur-Signature
   */

  // Volver a serializar en formato compacto y escapar los caracteres no ASCII
  // como \uXXXX (JSON.stringify no los escapa, Altur sí)
  const payloadString = JSON.stringify(payload).replace(
    /[\u0080-\uffff]/g,
    (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0")
  );

  // Decodificar el secreto base64
  const secretBuffer = Buffer.from(secret, "base64");

  // Generar la firma esperada
  const expected = crypto
    .createHmac("sha256", secretBuffer)
    .update(payloadString)
    .digest();
  const received = Buffer.from(signature || "", "base64");

  // timingSafeEqual lanza un error si las longitudes difieren, así que se comparan primero
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}

// Ejemplo de uso (con express.json())
const signature = req.headers["x-altur-signature"];
const isValid = isValidSignature(yourSecret, req.body, signature);

function isValidSignature($secret, $payload, $signature) {
    /*
     * Valida la firma de un webhook de Altur.
     *
     * @param string $secret Llave secreta compartida codificada en base64
     * @param object $payload Body decodificado con json_decode($raw), SIN `true`
     * @param string $signature Firma codificada en base64 del header X-Altur-Signature
     */

    // Volver a serializar en formato compacto. json_encode escapa los
    // caracteres no ASCII como \uXXXX por defecto, igual que Altur.
    $payloadString = json_encode($payload, JSON_UNESCAPED_SLASHES);

    // Decodificar el secreto base64
    $secretBytes = base64_decode($secret);

    // Generar la firma esperada
    $expectedSignature = base64_encode(
        hash_hmac('sha256', $payloadString, $secretBytes, true)
    );

    // Comparar firmas con comparación timing-safe
    return hash_equals($expectedSignature, (string) $signature);
}

// Ejemplo de uso
$signature = $_SERVER['HTTP_X_ALTUR_SIGNATURE'] ?? '';
// Decodifica como objetos: json_decode(..., true) convierte `{}` (p. ej. un
// extracted_data vacío) en `[]`, que se re-codifica distinto y rompe la firma.
$payload = json_decode(file_get_contents('php://input'));
$isValid = isValidSignature($yourSecret, $payload, $signature);

​

Ejemplo de Uso

request_body = request.get_json()  # JSON parseado por tu framework web
signature = request.headers.get("X-Altur-Signature", "")
shared_secret = "tu-secreto-codificado-en-base64"

if is_valid_signature(shared_secret, request_body, signature):
    print("Webhook válido!")
else:
    print("Webhook inválido!")

​

Headers Enviados con el Webhook

• Content-Type: application/json
• X-Altur-Signature: hash HMAC SHA-256 codificado en base64 del payload JSON compacto (ver arriba; no es el body crudo)

​

Por Qué Importa

• La solicitud proviene de Altur.
• El payload no fue modificado en tránsito.

​

Política de Reintentos

• Intentos máximos: 5 (entrega inicial más 4 reintentos).
• Backoff: 60s después del primer fallo, duplicándose en cada intento (60s, 2m, 4m, 8m).

​

Ejemplo de Flujo

1. Configura tu Endpoint Crea un endpoint en tu backend, por ejemplo /webhooks/altur/on-call-end. Debe ser accesible públicamente y aceptar solicitudes POST con Content-Type: application/json.
2. Parsea el Payload Extrae y procesa el payload JSON enviado por Altur. Maneja casos como payloads malformados o campos faltantes para evitar errores en runtime.
3. Valida la Autenticidad Usa el header X-Altur-Signature para verificar la autenticidad. Esto implica:
   • Recomputar la firma HMAC usando el secreto compartido y el payload parseado, re-serializado como JSON compacto.
   • Compararla con la firma del header.
4. Responde Rápido Devuelve 200 OK para confirmar la recepción. Altur hace timeout a los 5 segundos, así que responde mucho antes de ese límite para evitar reintentos innecesarios.
5. Registra los Eventos Guarda logs de las solicitudes y del procesamiento para tener trazabilidad. Es especialmente útil al depurar problemas con payloads o reintentos.
6. Maneja los Reintentos Diseña tu sistema para tolerar reintentos. Asegúrate de que tu endpoint sea idempotente: procesar el mismo evento varias veces no debe duplicar acciones (por ejemplo, inserts en BD o llamadas a APIs).

​

Buenas Prácticas

1. Asegura tu Endpoint
   • Autentica las Solicitudes: Verifica la firma HMAC en cada request. Usa un secreto único y seguro por integración.
   • Restringe el Acceso: Usa whitelisting de IP o firewall para permitir solicitudes únicamente desde los servidores de Altur.
   • Cifra la Comunicación: Usa HTTPS para que los datos viajen cifrados.
2. Registra los Eventos
   • Registra Todo: Guarda timestamps, headers, payloads y respuestas de cada solicitud entrante.
   • Monitorea Fallos: Configura alertas para fallos repetidos o solicitudes inválidas.
   • Mantén Logs: Retén los logs por un periodo razonable para auditoría o debugging.
3. Prueba Bien
   • Simula Eventos: Usa el dashboard de Altur para simular eventos y confirmar que tu endpoint los maneja correctamente.
   • Prueba Casos Borde: Payloads malformados, payloads grandes, campos faltantes.
   • Usa Entornos de Staging: Mantén un endpoint dedicado para pruebas, separado de producción.
4. Optimiza el Rendimiento
   • Responde Rápido: Altur hace timeout a los 5 segundos. Si el procesamiento es más largo, responde 200 OK de inmediato y procesa en background.
   • Minimiza el Procesamiento: Haz solo validación ligera y encolado en el endpoint; deja el trabajo pesado a workers.
   • Usa Caching: Cuando aplique, cachea respuestas para solicitudes redundantes.
5. Sé Idempotente
   • Evita Acciones Duplicadas: Diseña el sistema para que los reintentos no causen operaciones duplicadas (inserts en BD, llamadas a APIs). En los eventos de campaña, deduplica con event_id. Los eventos de llamada (on_call_end, transfer_started, transfer_completed) no tienen event_id, así que deduplica con id junto con event_type.
6. Comunica los Fallos
   • Devuelve Status Codes Correctos: Usa 400 para solicitudes inválidas, 500 para errores del servidor, etc. Recuerda que las respuestas 4xx distintas de 408 y 429 no se reintentan.
   • Loguea y Notifica: Registra los fallos y considera notificar al equipo si los reintentos críticos se agotan.

​

Solución de Problemas con la Validación de Firma

​

1. Formato de Serialización JSON

• Parsea y vuelve a serializar: No calcules el HMAC sobre el body crudo. Tiene espacios y no coincidirá.
• Formato compacto: Sin espacios después de comas ni de dos puntos.
• No ASCII escapado: Caracteres como í o ñ deben escaparse como \uXXXX (Sofía → Sof\u00eda). JSON.stringify no lo hace; consulta el ejemplo de JavaScript.
• Orden consistente: Conserva las llaves en el orden en que se recibieron.
• PHP: Usa json_decode($raw), no json_decode($raw, true). Los arrays asociativos convierten {} en [].

# ✅ Correcto - JSON compacto
json.dumps(data, separators=(',', ':'))

# ❌ Incorrecto - incluye espacios
json.dumps(data)  # Resultado: {"key": "value"}

# ❌ Incorrecto - no escapa caracteres no ASCII
json.dumps(data, separators=(',', ':'), ensure_ascii=False)

​

2. Formato de la Llave Secreta

• Tu secreto debe estar codificado en base64.
• Debe ser el mismo configurado en tu integración de webhook en Altur.

​

3. Nombre del Header

• El header es X-Altur-Signature (algunos frameworks son case-sensitive).
• Confirma que estás leyendo el header correcto.

​

4. Timing Attacks

• Python: hmac.compare_digest()
• Node.js: crypto.timingSafeEqual()
• PHP: hash_equals()

​

5. Probar tu Implementación

# Datos de prueba
test_payload = {"test": "data"}
test_secret = "dGVzdC1zZWNyZXQ="  # base64 de "test-secret"
expected_signature = "6RQRnEGhLZoG7UMG+fPBzjLuZhjLsG9U8AooC6LceYU="

# Debe devolver True
result = is_valid_signature(test_secret, test_payload, expected_signature)
print(f"Resultado de validación: {result}")