Webhooks ★Data Center

Mit Webhooks erhalten externe Anwendungen Benachrichtigungen in Echtzeit, wenn im Babel Licensing Service bestimmte Ereignisse eintreten. Verwenden Sie sie, um Ihre vorhandenen Systeme anzubinden, Abläufe zu automatisieren und Daten synchron zu halten.

Webhooks aufrufen

Webhooks erreichen Sie über das Hauptnavigationsmenü des Babel Licensing Service. Klicken Sie in der linken Seitenleiste auf den Menüeintrag „Webhooks“, um die Verwaltung der Webhooks zu öffnen.

Webhooks verwalten

Webhooks anzeigen

Die Webhook-Seite zeigt eine Tabelle aller konfigurierten Webhook-Abonnements mit ihren Details:

• Name: Ein beschreibender Name des Webhooks
• URL: Der Endpunkt, an den die Ereignisbenachrichtigungen gesendet werden. Die URL wird nur dann als anklickbarer Link angezeigt, wenn sie http oder https verwendet.
• Event: Der Ereignistyp, den der Webhook abonniert hat
• Owner User: Der Benutzer, der den Webhook angelegt hat
• Sent At: Der Zeitstempel der letzten Zustellung eines Ereignisses
• Next Retry: Der Zeitpunkt des nächsten Zustellversuchs (falls zutreffend)
• Status: Aktueller Status des Webhooks (OK, Error und so weiter)

Einen neuen Webhook hinzufügen

Einen Webhook bearbeiten

Einen Webhook löschen

Einen Webhook testen

Das System verarbeitet das Testereignis über denselben Zustellmechanismus wie echte Ereignisse, mit denselben Headern und derselben Signaturprüfung. So können Sie prüfen, wie Ihr Endpunkt die Nutzdaten eines Webhooks verarbeitet.

Details eines Webhook-Ereignisses

Wenn ein Webhook ausgelöst wurde, zeigt die aufgeklappte Ansicht die Details der Zustellung:

• Timestamp: Zeitpunkt, zu dem das Ereignis eingetreten ist
• Event Type: Der Ereignistyp (zum Beispiel license.created)
• Status: Status der Zustellung (OK, Failed)
• Response: Die Antwort, die Ihr Endpunkt zurückgegeben hat
• Error: Etwaige Fehlermeldungen (falls die Zustellung fehlgeschlagen ist)
• Retry Count: Anzahl der Zustellversuche
• Next Retry: Zeitpunkt des nächsten erneuten Versuchs (falls zutreffend)

Unterstützte Ereignisse

Der Babel Licensing Service unterstützt folgende Webhook-Ereignisse:

Lizenzen

• license.created Wird ausgelöst, wenn eine neue Lizenz erstellt wird.
• license.updated Wird ausgelöst, wenn eine vorhandene Lizenz aktualisiert wird.
• license.deleted Wird ausgelöst, wenn eine Lizenz gelöscht wird.
• license.expiring Wird ausgelöst, wenn eine Lizenz in Kürze abläuft.
• license.expired Wird ausgelöst, wenn eine Lizenz abgelaufen ist.
• license.revoked Wird ausgelöst, wenn eine Lizenz widerrufen wird.
• license.supportexpiring Wird ausgelöst, wenn die Wartung einer Lizenz in Kürze abläuft.
• license.supportexpired Wird ausgelöst, wenn die Wartung einer Lizenz abgelaufen ist.
• license.activated Wird ausgelöst, wenn eine Lizenz aktiviert wird.
• license.deactivated Wird ausgelöst, wenn eine Lizenz deaktiviert wird.
• license.requested Wird ausgelöst, wenn eine Lizenz angefordert wird.
• license.released Wird ausgelöst, wenn eine Lizenz freigegeben wird.

Bestellungen

• order.created Wird ausgelöst, wenn eine neue Bestellung angelegt wird.
• order.updated Wird ausgelöst, wenn eine vorhandene Bestellung aktualisiert wird.
• order.deleted Wird ausgelöst, wenn eine Bestellung gelöscht wird.

Berichte

report.created Wird ausgelöst, wenn ein neuer Bericht erstellt wird.

Referenz der Webhook-Nutzdaten

Dieser Abschnitt beschreibt im Detail, wie die Nutzdaten der Webhook-Ereignisse für die verschiedenen Ereignistypen aufgebaut sind und was sie enthalten.

Nutzdaten eines Lizenzereignisses

Bei einem Lizenzereignis (etwa license.created) enthalten die Nutzdaten folgende Felder:

{
    "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"
}

Nutzdaten eines Bestellereignisses

Bei Bestellereignissen (etwa order.created) enthalten die Nutzdaten des Webhooks diese Felder:

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

Nutzdaten eines Berichtsereignisses

Bei Berichtsereignissen (etwa report.created) enthalten die Nutzdaten des Webhooks diese Felder:

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

Zustellung von Webhooks und Wiederholungslogik

Der Babel Licensing Service verarbeitet Webhooks in einem Hintergrunddienst, der ständig läuft:

• Der Dienst prüft alle 30 Sekunden, ob neue Webhook-Ereignisse vorliegen
• Webhooks werden in Stapeln von bis zu 50 Ereignissen verarbeitet
• Das System verarbeitet sowohl ausstehende (neue) Ereignisse als auch zuvor fehlgeschlagene Ereignisse, für die ein erneuter Versuch geplant ist
• Jede Webhook-Zustellung enthält Standardheader:
  • User-Agent: Kennzeichnet den Babel Licensing Service
  • X-Babel-Webhook-Id: Eindeutige Kennung der Webhook-Zustellung
  • X-Babel-Event: Der Typ des zugestellten Ereignisses
  • X-Babel-Timestamp: Zeitpunkt, zu dem das Ereignis versendet wurde
  • X-Babel-Signature: HMAC-SHA256-Signatur (falls ein Geheimnis konfiguriert ist)

Wiederholungsmechanismus

Für eine fehlgeschlagene Webhook-Zustellung gilt:

• Das System plant automatisch einen erneuten Versuch 5 Minuten später
• Für jeden Webhook lässt sich eine maximale Anzahl von Wiederholungen konfigurieren
• Fehlgeschlagene Ereignisse bleiben im System, bis sie erfolgreich zugestellt sind oder die maximale Anzahl von Wiederholungen erreicht ist
• Die Webhook-Oberfläche zeigt bei fehlgeschlagenen Zustellungen den Zeitpunkt des nächsten geplanten Versuchs
• Zu jeder fehlgeschlagenen Zustellung wird die Fehlermeldung oder der HTTP-Statuscode für die Fehlerbehebung gespeichert

Webhook-Status

Webhooks können im System folgende Status haben:

• OK: Das Ereignis wurde erfolgreich zugestellt
• Failed: Die Zustellung ist fehlgeschlagen, und die maximale Anzahl von Wiederholungen wurde überschritten
• Pending: Das Ereignis wartet auf die Verarbeitung
• Scheduled: Die Zustellung ist fehlgeschlagen, und ein erneuter Versuch ist geplant

Webhooks absichern

Alle Webhook-Anfragen enthalten eine Signatur im Header X-Babel-Signature. Diese Signatur wird mit HMAC-SHA256 aus dem Geheimnis Ihres Webhooks und dem Anfragetext erzeugt.

So prüfen Sie den Webhook:

Beispielcode für die Prüfung (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;
}

Einen Webhook-Empfänger implementieren

Das folgende vollständige Beispiel zeigt, wie Sie in ASP.NET Core einen Webhook-Empfänger implementieren, der die Signaturen der Webhooks ordnungsgemäß validiert:

// 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();
        }
    }
}

Bewährte Vorgehensweisen für den Empfang von Webhooks

Beachten Sie bei der Implementierung eines Webhook-Empfängers:

1. Signaturen immer validieren: Prüfen Sie mit dem bereitgestellten Code zur Signaturvalidierung die Echtheit jedes Webhooks
2. Webhook-Geheimnis sicher speichern: Schreiben Sie es nicht fest in den Code wie im Beispiel, sondern verwenden Sie ein sicheres Konfigurationssystem
3. Schnell antworten: Geben Sie eine Antwort 200 OK zurück, sobald Sie die Signatur validiert haben
4. Asynchron verarbeiten: Verarbeiten Sie den Webhook nach der Validierung und der Antwort in einem Hintergrundthread oder einer Warteschlange
5. Idempotenz implementieren: Verwenden Sie die Ereignis-ID, damit mehrfach zugestellte Webhooks nicht doppelt verarbeitet werden
6. Alle Webhook-Ereignisse protokollieren: Zeichnen Sie alle empfangenen Webhooks für Debugging und Prüfungen auf

Webhook-Ereignisse verarbeiten

Verschiedene Ereignistypen behandeln

Ihr Webhook-Empfänger sollte so angelegt sein, dass er die verschiedenen Ereignistypen passend behandelt. Das folgende Beispiel zeigt, wie Sie nach der Validierung der Signatur verschiedene Webhook-Ereignisse verarbeiten können:

// 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");
    }
}

Fehlerbehebung

Häufige Probleme

• Webhook empfängt keine Ereignisse: Prüfen Sie den Status des Webhooks im Dashboard und ob Sie den Ereignistyp abonniert haben
• Authentifizierungsfehler: Prüfen Sie, ob Ihr Code zur Signaturvalidierung korrekt ist und ob Sie dasselbe Geheimnis verwenden, das im Webhook konfiguriert ist
• Zeitüberschreitungen: Stellen Sie sicher, dass Ihr Endpunkt in angemessener Zeit antwortet (das System wartet auf eine Antwort, bevor es die Zustellung als erfolgreich kennzeichnet)
• Ungültige URL: Prüfen Sie, ob Ihre Webhook-URL aus dem Internet erreichbar ist und HTTP-Statuscodes 2xx zurückgibt
• Benutzerdefinierte Header werden nicht angewendet: Prüfen Sie das Format Ihrer benutzerdefinierten Header in der Konfiguration des Webhooks
• Webhook als fehlgeschlagen gekennzeichnet: Sehen Sie in den Details des Webhooks in der Fehlermeldung nach, welcher HTTP-Statuscode oder welche Ausnahme aufgetreten ist

Webhook-Verlauf anzeigen

Zu jedem Webhook können Sie den vollständigen Zustellverlauf einsehen:

1. Klicken Sie in der Hauptliste auf einen Webhook, um seine Details aufzuklappen
2. Der Abschnitt mit dem Verlauf zeigt alle Zustellversuche mit Zeitstempeln, Ereignistypen, Status und etwaigen Fehlermeldungen
3. Mit diesen Informationen diagnostizieren Sie Zustellprobleme oder bestätigen erfolgreiche Zustellungen