Sicurezza Webhooks

Proteggi i tuoi webhook endpoint verificando l'autenticità delle richieste.

Firma HMAC

Ogni richiesta include una firma HMAC-SHA256:

X-BladeCRM-Signature: sha256=abc123def456...

Verificare la Firma

1. Ottieni il Secret

Quando crei un webhook, viene generato un secret. Copialo e conservalo in modo sicuro.

2. Calcola la Firma

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected, signature)

3. Confronta

Se le firme corrispondono, la richiesta è autentica.

Esempi

Node.js

const crypto = require('crypto');

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

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-bladecrm-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Processa il webhook
  res.status(200).send('OK');
});

PHP

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

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_BLADECRM_SIGNATURE'];

if (!verifyWebhook($payload, $signature, WEBHOOK_SECRET)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Processa il webhook
http_response_code(200);

Best Practices

• ✅ Verifica sempre la firma
• ✅ Usa timing-safe comparison
• ✅ Conserva il secret in modo sicuro
• ✅ Usa HTTPS per l'endpoint
• ✅ Rigenerale il secret periodicamente

Rigenerare il Secret

Se pensi che il secret sia compromesso:

1. Impostazioni → Webhooks
2. Seleziona il webhook
3. Rigenera Secret
4. Aggiorna il secret nel tuo server

---

WARNING

Non saltare la verifica della firma. Senza, chiunque potrebbe inviare richieste false al tuo endpoint.