Webhook ★Data Center

I webhook permettono alle applicazioni esterne di ricevere notifiche in tempo reale quando nel Babel Licensing Service si verificano determinati eventi. Usali per collegare i tuoi sistemi esistenti, automatizzare i flussi di lavoro e mantenere i dati sincronizzati.

Accedere ai webhook

I webhook sono disponibili dal menu di navigazione principale del Babel Licensing Service. Fai clic sulla voce di menu “Webhooks” nella barra laterale sinistra per aprire l’interfaccia di gestione dei webhook.

Gestire i webhook

Consultare i webhook

La pagina dei webhook mostra una tabella con tutte le sottoscrizioni webhook configurate e i relativi dettagli:

• Name: un nome descrittivo del webhook
• URL: l’endpoint a cui vengono inviate le notifiche degli eventi. L’URL è mostrato come collegamento su cui fare clic solo quando usa http o https.
• Event: il tipo di evento a cui il webhook è sottoscritto
• Owner User: l’utente che ha creato il webhook
• Sent At: la data e l’ora dell’ultima consegna di un evento
• Next Retry: quando avverrà il prossimo tentativo di consegna (se previsto)
• Status: lo stato corrente del webhook (OK, Error e simili)

Aggiungere un nuovo webhook

Modificare un webhook

Eliminare un webhook

Provare un webhook

Il sistema elabora l’evento di prova con lo stesso meccanismo di consegna degli eventi reali, comprese le stesse intestazioni e la stessa verifica della firma, così puoi verificare come il tuo endpoint gestisce i payload dei webhook.

Dettagli degli eventi di un webhook

Quando un webhook viene attivato, la vista espansa mostra i dettagli della consegna:

• Timestamp: quando si è verificato l’evento
• Event Type: il tipo di evento (per esempio license.created)
• Status: lo stato della consegna (OK, Failed)
• Response: la risposta ricevuta dal tuo endpoint
• Error: gli eventuali messaggi di errore (se la consegna non è riuscita)
• Retry Count: il numero di tentativi di consegna
• Next Retry: quando avverrà il prossimo nuovo tentativo (se previsto)

Eventi supportati

Il Babel Licensing Service supporta i seguenti eventi webhook:

Licenze

• license.created Generato quando viene creata una nuova licenza.
• license.updated Generato quando una licenza esistente viene aggiornata.
• license.deleted Generato quando una licenza viene eliminata.
• license.expiring Generato quando una licenza sta per scadere.
• license.expired Generato quando una licenza è scaduta.
• license.revoked Generato quando una licenza viene revocata.
• license.supportexpiring Generato quando la manutenzione di una licenza sta per scadere.
• license.supportexpired Generato quando la manutenzione di una licenza è scaduta.
• license.activated Generato quando una licenza viene attivata.
• license.deactivated Generato quando una licenza viene disattivata.
• license.requested Generato quando una licenza viene richiesta.
• license.released Generato quando una licenza viene rilasciata.

Ordini

• order.created Generato quando viene creato un nuovo ordine.
• order.updated Generato quando un ordine esistente viene aggiornato.
• order.deleted Generato quando un ordine viene eliminato.

Report

report.created Generato quando viene creato un nuovo report.

Riferimento dei payload dei webhook

Questa sezione descrive in dettaglio la struttura e il contenuto dei payload degli eventi webhook per i diversi tipi di evento.

Payload degli eventi delle licenze

Quando gestisci un evento di una licenza (come license.created), il payload contiene i seguenti campi:

{
    "id": 101,
    "licenseId": "LIC-0001",
    "userKey": "XJK-SHJD-GE5E",
    "licensee": "Acme Corp",
    "licensingMode": 1,
    "issueDate": "2025-03-16T00:00:00Z",
    "supportExpireDate": "2026-03-16T00:00:00Z",
    "expireDate": "2025-12-31T23:59:59Z",
    "customerId": 501,
    "orderId": 302,
    "templateId": 10,
    "revoked": false,
    "trace": false,
    "eventType": "license.created",
    "timestamp": "2025-03-16T12:00:00Z"
}

Payload degli eventi degli ordini

Per gli eventi relativi agli ordini (come order.created), il payload del webhook contiene questi campi:

{
    "id": 202,
    "orderNumber": "ORD-12345",
    "customerId": 501,
    "createdAt": "2025-03-16T12:00:00Z",
    "status": "completed",
    "eventType": "order.created",
    "timestamp": "2025-03-16T12:05:00Z"
}

Payload degli eventi dei report

Per gli eventi relativi ai report (come report.created), il payload del webhook contiene questi campi:

{
    "id": 303,
    "name": "Monthly Report",
    "date": "2025-03-15T00:00:00Z",
    "eventType": "report.created",
    "timestamp": "2025-03-16T12:10:00Z"
}

Consegna dei webhook e logica dei nuovi tentativi

Il Babel Licensing Service elabora i webhook con un servizio in background che è sempre in esecuzione:

• Il servizio controlla la presenza di nuovi eventi webhook ogni 30 secondi
• I webhook vengono elaborati in lotti di 50 eventi al massimo
• Il sistema gestisce sia gli eventi in attesa (nuovi) sia quelli non riusciti in precedenza e pianificati per un nuovo tentativo
• Ogni consegna di un webhook include le intestazioni standard:
  • User-Agent: identifica il Babel Licensing Service
  • X-Babel-Webhook-Id: identificatore univoco della consegna del webhook
  • X-Babel-Event: il tipo di evento consegnato
  • X-Babel-Timestamp: quando l’evento è stato inviato
  • X-Babel-Signature: firma HMAC-SHA256 (se è configurato un segreto)

Meccanismo dei nuovi tentativi

Quando la consegna di un webhook non riesce:

• Il sistema pianifica automaticamente un nuovo tentativo dopo 5 minuti
• Per ogni webhook si può configurare un numero massimo di nuovi tentativi
• Gli eventi non riusciti restano nel sistema finché non vengono consegnati o finché non si raggiunge il numero massimo di nuovi tentativi
• L’interfaccia dei webhook mostra l’ora del prossimo nuovo tentativo pianificato per le consegne non riuscite
• Ogni consegna non riuscita conserva il messaggio di errore o il codice di stato HTTP, utile per la risoluzione dei problemi

Stato dei webhook

I webhook nel sistema possono avere i seguenti stati:

• OK: l’evento è stato consegnato
• Failed: la consegna dell’evento non è riuscita e il numero massimo di nuovi tentativi è stato superato
• Pending: l’evento è in attesa di essere elaborato
• Scheduled: la consegna dell’evento non è riuscita ed è pianificato un nuovo tentativo

Proteggere i webhook

Tutte le richieste webhook contengono una firma nell’intestazione X-Babel-Signature. La firma viene generata con HMAC-SHA256 usando come input la chiave segreta del tuo webhook e il corpo della richiesta.

Per verificare il webhook:

Esempio di codice di verifica (C#):

private bool VerifyWebhookSignature(string payload, string signatureHeader, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var computedHash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var computedSignature = Convert.ToBase64String(computedHash);
    
    return signatureHeader == computedSignature;
}

Implementare un ricevitore di webhook

Di seguito trovi un esempio completo di come implementare in ASP.NET Core un ricevitore di webhook che convalida correttamente le firme dei webhook:

// WebhookValidator.cs
using System;
using System.Security.Cryptography;
using System.Text;
 
namespace YourProject.Utilities
{
    public static class WebhookValidator
    {
        /// <summary>
        /// Validates the webhook payload against the provided signature using HMAC-SHA256.
        /// </summary>
        /// <param name="payload">The raw JSON payload.</param>
        /// <param name="secret">The shared secret.</param>
        /// <param name="signature">The signature from the incoming request header.</param>
        /// <returns>True if the signature is valid; otherwise, false.</returns>
        public static bool ValidateSignature(string payload, string secret, string signature)
        {
            using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
            var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
            var computedSignature = BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant();
            return string.Equals(computedSignature, signature, StringComparison.OrdinalIgnoreCase);
        }
    }
}
 
// WebhookController.cs
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System.IO;
using System.Threading.Tasks;
using YourProject.Utilities;
 
namespace YourProject.Controllers
{
    [ApiController]
    [Route("api/webhook")]
    public class WebhookController : ControllerBase
    {
        private readonly ILogger<WebhookController> _logger;
        // Ideally, the secret comes from configuration
        private readonly string _webhookSecret = "your-webhook-secret";
        
        public WebhookController(ILogger<WebhookController> logger)
        {
            _logger = logger;
        }
        
        [HttpPost]
        public async Task<IActionResult> ReceiveWebhook()
        {
            // Read the payload from the request body
            var payload = await new StreamReader(Request.Body).ReadToEndAsync();
            
            // Retrieve the signature from the request headers
            if (!Request.Headers.TryGetValue("X-Babel-Signature", out var incomingSignature))
            {
                _logger.LogWarning("Missing X-Babel-Signature header");
                return Unauthorized("Signature header missing");
            }
            
            // Validate the signature
            if (!WebhookValidator.ValidateSignature(payload, _webhookSecret, incomingSignature))
            {
                _logger.LogWarning("Invalid webhook signature");
                return Unauthorized("Invalid signature");
            }
            
            // Process the webhook payload
            _logger.LogInformation("Webhook payload validated and processed");
            
            // TODO: Deserialize and process the payload as needed
            
            return Ok();
        }
    }
}

Procedure consigliate per ricevere i webhook

Quando implementi un ricevitore di webhook:

1. Convalida sempre le firme: usa il codice di convalida della firma fornito per verificare l’autenticità di ogni webhook
2. Conserva in modo sicuro il segreto del webhook: non scriverlo nel codice come nell’esempio; usa un sistema di configurazione sicuro
3. Rispondi rapidamente: restituisci una risposta 200 OK non appena hai convalidato la firma
4. Elabora in modo asincrono: dopo aver convalidato la firma e restituito la risposta, elabora il webhook in un thread in background o in una coda
5. Implementa l’idempotenza: usa l’ID dell’evento per non elaborare webhook duplicati, se vengono consegnati più di una volta
6. Registra nel log tutti gli eventi webhook: conserva traccia di tutti i webhook ricevuti per il debug e per le verifiche

Elaborare gli eventi webhook

Gestire i diversi tipi di evento

Il tuo ricevitore di webhook deve essere progettato per gestire in modo appropriato i diversi tipi di evento. Ecco un esempio di come puoi elaborare vari eventi webhook dopo aver convalidato la firma:

// Example of webhook event processing
private async Task ProcessWebhookEvent(string payload, string eventType)
{
    switch (eventType)
    {
        case "license.created":
            await ProcessNewLicense(payload);
            break;
            
        case "license.expired":
            await ProcessExpiredLicense(payload);
            break;
            
        case "order.created":
            await ProcessNewOrder(payload);
            break;
            
        // Handle other event types
            
        default:
            _logger.LogWarning($"Unhandled webhook event type: {eventType}");
            break;
    }
}
 
// Example deserialization and processing
private async Task ProcessNewLicense(string payload)
{
    try
    {
        // Deserialize the payload
        var licenseEvent = JsonSerializer.Deserialize<LicenseCreatedEvent>(payload);
        
        // Process the license
        _logger.LogInformation($"Processing new license: {licenseEvent.LicenseId}");
        
        // Example: Store in your database, notify users, etc.
        await _licenseService.SyncLicenseAsync(licenseEvent.Id);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error processing license.created webhook");
    }
}

Risoluzione dei problemi

Problemi comuni

• Il webhook non riceve eventi: controlla lo stato del webhook nella dashboard e verifica che il tipo di evento sia uno di quelli a cui ti sei sottoscritto
• Errori di autenticazione: verifica che il codice di convalida della firma sia corretto e che tu stia usando lo stesso segreto configurato nel webhook
• Timeout: assicurati che il tuo endpoint risponda entro un tempo ragionevole (il sistema attende una risposta prima di considerare riuscita la consegna)
• URL non valido: controlla che l’URL del webhook sia raggiungibile da Internet e restituisca codici di stato HTTP 2xx
• Intestazioni personalizzate non applicate: rivedi il formato delle intestazioni personalizzate nella configurazione del webhook
• Webhook contrassegnato come non riuscito: controlla il messaggio di errore nei dettagli del webhook per vedere il codice di stato HTTP o l’eccezione che si è verificata

Consultare la cronologia dei webhook

Per ogni webhook puoi consultare la cronologia completa delle consegne:

1. Fai clic su un webhook nell’elenco principale per espanderne i dettagli
2. La sezione della cronologia mostra tutti i tentativi di consegna con data e ora, tipo di evento, stato ed eventuali messaggi di errore
3. Usa queste informazioni per diagnosticare i problemi di consegna o per verificare che le consegne siano riuscite