Webhooks salientes del CRM

Qué son

Son callbacks HTTP que el CRM envía a tu sistema cuando ocurren eventos.

Endpoints API para gestionar webhooks

• GET /api/v1/webhooks
• POST /api/v1/webhooks
• GET /api/v1/webhooks/{id}
• DELETE /api/v1/webhooks/{id}
• POST /api/v1/webhooks/{id}/test

Eventos permitidos hoy

• client.created
• client.updated
• prospect.created
• prospect.updated
• prospect.converted

Alta de webhook

curl -s -X POST https://tu-crm.nexgestion.es/api/v1/webhooks \
  -H "Authorization: Bearer crm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ERP Receptor",
    "url": "https://mi-sistema.com/webhooks/crm",
    "events": ["client.created", "client.updated"]
  }'

Guarda el secret que devuelve la creación: solo se muestra una vez.

Validación de firma en tu receptor

Cabecera: X-CRM-Signature Algoritmo: HMAC-SHA256(payload_raw, secret)

PHP ejemplo:

$raw = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CRM_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Firma inválida');
}

Recomendaciones

• Implementa idempotencia por event + ts + id (o hash payload).
• Responde rápido (2xx) y procesa en cola.
• Loguea intentos y errores.
• Usa endpoint /test al dar de alta.