Webhooks salientes (integrar tu CRM/ERP)

Si tienes desarrollador propio y quieres conectar Equipia con tu CRM, ERP o sistema interno, podemos hacer POST a tu endpoint cada vez que ocurre un evento importante.

Eventos disponibles (v1)

• lead.qualified — agente SDR califica un lead.
• payment.collected — cobro mensual exitoso de Flow.
• ticket.created — ticket de soporte nuevo.
• subscription.changed — cambio de plan aplicado.
• conversation.started / conversation.ended — placeholder (próxima iteración).

Cómo configurar

1. Configuración → tab Webhooks → 'Crear webhook nuevo'.
2. Pega tu URL HTTPS + marca los eventos.
3. Guardamos el secret UNA SOLA VEZ — cópialo a tu app.
4. Hacemos POST a tu endpoint con header X-Equipia-Signature: sha256=.
5. Tu endpoint debe responder 2xx en < 10 segundos. Reintentamos con backoff (30s, 2m, 10m, 1h, 6h) hasta 5 veces.

Validar firma HMAC — Node.js

const crypto = require('crypto');
function verify(body, signature, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Validar firma — Python

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Validar firma — PHP

function verify($body, $signature, $secret) {
  $expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
  return hash_equals($expected, $signature);
}

Manejo de fallos

Si tu endpoint devuelve error 5xx o no responde, reintentamos automáticamente. Después de 5 reintentos fallidos consecutivos para un mismo evento, lo marcamos como 'dead' y no insistimos. Si acumulas 10 entregas 'dead' consecutivas, desactivamos el webhook automáticamente y te avisamos por email.