Guida ai webhook

1. Crea un endpoint webhook

Innanzitutto, crea un endpoint HTTP nella tua applicazione in grado di ricevere richieste POST da LicenseChain.

// Express.js Example
app.post('/webhooks/licensechain', async (req, res) => {'{'}
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);
  
  // Verify signature (see Security section)
  if (!verifySignature(payload, signature, timestamp, webhookSecret)) {'{'}
    return res.status(401).send('Invalid signature');
  {'}'}
  
  // Process webhook event
  const event = req.body;
  console.log('Received event:', event.type, event.data);
  
  res.status(200).send('OK');
{'}'});

2. Registra il tuo webhook

Utilizza l'API LicenseChain per registrare il tuo endpoint webhook. Dovrai fornire l'URL e specificare quali eventi desideri ricevere.

POST /v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://your-app.com/webhooks/licensechain",
  "events": ["license.created", "license.updated", "license.revoked"],
  "secret": "optional-custom-secret"
{'}'}

3. Eventi disponibili

LicenseChain supporta i seguenti eventi webhook:

Firme dei webhook

Tutte le richieste webhook includono una firma nel file X-Webhook-Signature intestazione. La firma è HMAC-SHA256 del corpo della richiesta non elaborata che utilizza il segreto del webhook. Verificare sempre utilizzando confronto in tempo costante (per esempio. crypto.timingSafeEqual) per prevenire attacchi temporali. Il valore dell'intestazione può essere esadecimale o non elaborato sha256= seguito da esadecimale; spogliare il sha256= prefisso prima di confrontare i buffer esadecimali in modo che le lunghezze corrispondano.

// Node.js Example (constant-time, supports sha256= prefix)
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {'{'}
  if (!payload || !signature || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  const received = String(signature).startsWith('sha256=') ? String(signature).slice(7) : String(signature);
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(received, 'hex');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
{'}'}

// In your webhook handler (use raw body for payload)
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody || JSON.stringify(req.body);
if (!verifySignature(payload, signature, webhookSecret)) {'{'}
  return res.status(401).send('Invalid signature');
{'}'}

Richiedi intestazioni

LicenseChain include le seguenti intestazioni con ciascuna richiesta webhook:

Elenca tutti i webhook

GET /v1/webhooks?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Ottieni i dettagli del webhook

GET /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Aggiorna webhook

PUT /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://new-url.com/webhooks",
  "events": ["license.created", "license.updated"]
{'}'}

Elimina webhook

DELETE /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Invia webhook di prova

Puoi testare il tuo endpoint webhook senza attendere che si verifichi un evento reale:

POST /v1/webhooks/:id/test
Authorization: Bearer YOUR_API_KEY

Questo invierà un evento di prova al tuo URL webhook con un payload di esempio. Usalo per verificare che il tuo endpoint funzioni correttamente.

Visualizza i log dei webhook

Controlla lo stato di consegna e la risposta per ciascun evento webhook:

GET /v1/webhooks/:id/logs?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

I log includono il codice di stato HTTP, il corpo della risposta e se la consegna ha avuto esito positivo.

✅Verifica sempre le firme

Non elaborare mai gli eventi webhook senza verificare la firma. Ciò garantisce che la richiesta provenga da LicenseChain e non sia stata manomessa.

✅ Rispondi rapidamente

L'endpoint webhook dovrebbe rispondere entro 5 secondi. Per le operazioni a lunga esecuzione, riconoscere immediatamente il webhook ed elaborarlo in modo asincrono.

✅ Gestire l'idempotenza

Utilizza l'ID evento per impedire l'elaborazione più volte dello stesso evento. Memorizza gli ID evento elaborati e controlla prima dell'elaborazione.

✅ Utilizza HTTPS

Utilizza sempre HTTPS per gli endpoint webhook per garantire che i dati siano crittografati durante il transito.

✅ Monitora i log dei webhook

Controlla regolarmente i log dei webhook per identificare e risolvere i problemi di consegna. Imposta avvisi per consegne non riuscite.

Il webhook non riceve eventi

• • Verificare che l'URL del webhook sia accessibile da Internet
• • Verificare che l'endpoint restituisca un codice di stato 2xx
• • Assicurati che gli eventi a cui sei iscritto si stiano effettivamente verificando
• • Esaminare i log dei webhook per individuare eventuali errori di consegna

Verifica della firma non riuscita

• • Assicurati di utilizzare il segreto del webhook corretto
• • Verifica di firmare il corpo esatto della richiesta (come stringa JSON)
• • Verifica di utilizzare l'algoritmo HMAC-SHA256
• • Assicurati che le intestazioni vengano lette correttamente (con distinzione tra maiuscole e minuscole)

Errori di timeout

• • Ottimizza il tuo gestore webhook per rispondere rapidamente
• • Spostare l'elaborazione pesante sui lavori in background
• • Restituire immediatamente 200 OK ed elaborare in modo asincrono