Webhooks

Los webhooks notifican a un endpoint externo cuando ocurre un cambio en NexGestión. Son útiles para sincronizar sistemas, iniciar procesos o actualizar una aplicación sin consultar continuamente la API.

ConfiguraciónCopy Anchor Link

Registra una URL HTTPS, selecciona los eventos necesarios y genera un secreto de firma. El secreto se muestra al crear la suscripción; guárdalo en un gestor de secretos y no lo publiques.

La suscripción se gestiona con la API y requiere los scopes de webhooks correspondientes. Comprueba el catálogo de eventos habilitado en tu espacio antes de suscribirte.

Petición enviadaCopy Anchor Link

El cuerpo es JSON y contiene un evento, una marca de tiempo y sus datos:

{
  "event": "client.updated",
  "ts": 1720000000,
  "data": {
    "id": "client_123"
  }
}

Las cabeceras de entrega permiten identificar y verificar la petición:

X-CRM-Event: client.updated
X-CRM-Delivery: delivery_example_123
X-CRM-Signature: sha256=<HEX_SIGNATURE>

La firma es un HMAC-SHA256 calculado sobre el cuerpo original, antes de decodificarlo o formatearlo. Verifica también que la marca de tiempo sea razonable y conserva X-CRM-Delivery para no procesar dos veces la misma entrega.

Ejemplo conceptual en PHP:

$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_CRM_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

Eventos habitualesCopy Anchor Link

El catálogo crece con el producto. Actualmente se agrupa en:

• clientes: creación y actualización;
• prospectos: creación, actualización y conversión;
• tickets: creación, respuesta, cambio de estado, cierre y reapertura;
• tareas: creación, actualización, finalización y asignación;
• calendario: creación, actualización y cancelación de eventos;
• formularios: cambios, publicación, enlace público y envíos;
• memoria de agentes: creación, actualización y eliminación.

ReintentosCopy Anchor Link

Responde con un código 2xx cuando hayas aceptado la entrega. Si tu endpoint falla o tarda demasiado, NexGestión puede reintentar con espera progresiva. Procesa de forma asíncrona cuando sea posible y diseña el consumidor para entregas duplicadas.

RecomendacionesCopy Anchor Link

• verifica firma, tiempo e idempotencia;
• responde rápido y mueve el trabajo pesado a una cola;
• registra evento, entrega, resultado y request_id, sin payloads sensibles;
• devuelve 4xx para peticiones que no deben reintentarse;
• rota el secreto si se expone.