Webhook de contactos

El webhook de contactos permite integrar Intely con cualquier sistema externo (CRM, ERP, base de datos propia). Una vez activado, Intely envía una solicitud POST con un documento JSON a la URL configurada cada vez que se crea un contacto o cambian sus tags o su etapa del embudo.

Cada solicitud está firmada con HMAC-SHA256 utilizando un secreto exclusivo de su cuenta, lo que permite verificar que el evento fue emitido por Intely. La integración completa consiste en los cinco pasos descriptos a continuación.

Implemente en su servidor una ruta que acepte solicitudes POST con cuerpo JSON. Requisitos:

• La URL debe ser pública y utilizar https://. No se aceptan direcciones internas ni redes privadas.
• Debe responder con un código 2xx en menos de 5 segundos. Si el procesamiento del evento es costoso, encole el trabajo y responda de inmediato.
• Conserve acceso al cuerpo crudo del request (antes de parsear el JSON): es necesario para verificar la firma en el paso 3.

1. Ingrese al dashboard de Intely y diríjase a Agente → Integraciones → Webhook.
2. Ingrese la URL de su endpoint y active la opción Habilitado.
3. Al guardar por primera vez, se genera el secreto de firma (whsec_...). Almacénelo de forma segura, por ejemplo en una variable de entorno: se muestra una única vez y no puede recuperarse. Si lo pierde o se ve comprometido, utilice la opción Rotar secreto, que genera uno nuevo e invalida el anterior de inmediato.

Cada solicitud incluye los siguientes encabezados:

POST /su-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Intely-Webhooks/1.0
X-Intely-Event: contact.updated
X-Intely-Delivery-Id: 5f0c2f9a-1b7e-4c3d-9a52-8f4e6d2b1c0a
X-Intely-Signature: t=1783558800,v1=a1b2c3d4e5f6...

La firma del header X-Intely-Signature se calcula como HMAC-SHA256(secreto, "{t}.{cuerpo}"), donde t es el timestamp Unix del envío y cuerpo es el cuerpo crudo del request. Para validarla:

1. Extraiga t y v1 del header.
2. Calcule el HMAC-SHA256 de la cadena {t}.{cuerpo} con su secreto y codifíquelo en hexadecimal.
3. Compare el resultado con v1 mediante una comparación en tiempo constante.
4. Rechace el evento si el timestamp difiere en más de 5 minutos de la hora actual (protección contra ataques de repetición).

import hashlib, hmac, time

def verificar_firma(header_firma: str, cuerpo: str, secreto: str) -> bool:
    """Valida el header X-Intely-Signature sobre el cuerpo crudo del request."""
    partes = dict(p.split("=") for p in header_firma.split(","))
    timestamp, firma_recibida = partes["t"], partes["v1"]

    firma_esperada = hmac.new(
        secreto.encode(),
        f"{timestamp}.{cuerpo}".encode(),
        hashlib.sha256,
    ).hexdigest()

    # Comparación en tiempo constante + ventana de tolerancia de 5 minutos
    if not hmac.compare_digest(firma_esperada, firma_recibida):
        return False
    return abs(time.time() - int(timestamp)) <= 300

El mismo procedimiento puede implementarse en cualquier lenguaje con soporte de HMAC-SHA256. Toda solicitud con firma inválida debe descartarse con un código 401.

Se emiten dos tipos de evento:

Ambos comparten la misma estructura:

{
  "version": 1,
  "event": "contact.updated",
  "sent_at": "2026-07-14T20:00:00+00:00",
  "data": {
    "id": 12345,
    "platform": "whatsapp",
    "name": "Juan Pérez",
    "phone": "5491122334455",
    "tags": [
      { "id": 7, "name": "interesado" },
      { "id": 12, "name": "departamento" }
    ],
    "stage": { "id": 4, "name": "Calificado" },
    "source_type": "whatsapp_ad",
    "created_at": "2026-07-14T19:58:00+00:00"
  }
}

Cada evento contiene el estado completo y actual del contacto, no un diferencial. Se recomienda realizar un upsert por data.id y conservar la última versión recibida.

Desde Agente → Integraciones → Webhook, utilice el botón Enviar evento de prueba. Intely enviará un evento firmado con datos ficticios que incluye el campo "test": true dentro de data, de modo que pueda distinguirlo de los eventos reales. Si su endpoint responde 2xx, la integración queda operativa y los eventos comenzarán a llegar automáticamente.