Billbee Webhooks einrichten und verwalten

Webhooks ermöglichen es dir, automatisierte Echtzeit-Benachrichtigungen von Billbee an deine eigene Anwendung oder Drittsysteme zu senden. Sobald ein bestimmtes Ereignis in Billbee eintritt (z.B. wenn eine Bestellung aktualisiert wird), sendet Billbee automatisch ein Datenpaket an die von dir hinterlegte URL.

In dieser Anleitung erfährst du, wie du Webhooks registrierst, den automatischen Handshake bewältigst und die Sicherheit der Datenübertragung via Signaturprüfung gewährleistest.

Webhooks registrieren

Die Registrierung eines Webhooks erfolgt einmalig über einen POST-Aufruf an die Billbee-API (z. B. via Postman oder direkt aus deinem Programmcode heraus).

API-Endpunkt & Authentifizierung

• Methode: POST  
• URL: https://app.billbee.io/api/v1/webhooks  
• Authentifizierung: Erfordert Basic Auth (bestehend aus deinem Billbee-Benutzernamen und deinem Billbee-API-Passwort).
• Zusätzlicher Header: Der HTTP-Header X-Billbee-Api-Key  muss mit deinem persönlichen Billbee-API-Key übergeben werden.

Beispiel für den Registrierungs-Request (Payload)

JSON

{
  "Secret": "my_webhook_secret_12345678901234567890",
  "WebHookUri": "https://your-url.com/api/webhooks/incoming/custom",
  "Filters": ["order.updated"],
  "Headers": { "X-Custom-Header": "MyValue" },
  "Properties": { "SystemId": "Shop_01" }
}

• Secret: Ein von dir frei gewählter, schwer zu erratender Text (Passwort). Dieses Secret wird niemals im Klartext übertragen. Es dient dazu, die Signatur im HTTP-Header ms-signature  nachfolgender Webhook-Anfragen zu berechnen, damit du die Echtheit der Daten prüfen kannst.
• WebHookUri: Die Ziel-Adresse deines Servers, die Billbee bei Ereignissen aufrufen soll.
• Filters: Hier definierst du, welche Ereignisse dich interessieren. Sie setzen sich immer aus einem Objekttyp und einer Aktion zusammen (z. B. order.updated ).
  • 
    

    Verfügbare Objekttypen: Order , Article , Customer , StockArticle  

  • 
    

    Verfügbare Aktionen: Created , Updated , Archived , Restored  

  • 
    

    Besonderheit: Wenn du ungefiltert alle Ereignisse empfangen möchtest, nutze stattdessen das Sternchen * .

• • Headers: optionale, benutzerdefinierte HTTP-Header, die Billbee bei jedem Aufruf an deinen Server mitsenden soll (z. B. zur Identifikation deines Systems).
• Properties: Benutzerdefinierte Datenfelder, die Billbee im Properties -Objekt des Webhook-Datenpakets (Payload) unverändert an dich zurückschickt.

Der Registrierungs-Handshake (Echo-Challenge)

Direkt nach dem Absenden der Registrierung führt Billbee eine Überprüfung durch, um sicherzustellen, dass deine Ziel-URL aktiv ist und unter deiner Kontrolle steht. Hierbei sendet Billbee einen GET-Aufruf an deine angegebene WebHookUri .

• Methode: GET  
• Parameter: Ein Query-String-Parameter namens echo , welcher eine zufällige Zeichenkette enthält.
• Anforderung an deinen Server: Dein System muss zwingend mit exakt derselben zufälligen Zeichenkette im Response-Body (als reiner Text / plain text ) antworten.

Webhooks verarbeiten & empfangen

Sobald das ausgewählte Ereignis in Billbee eintritt, sendet Billbee ein JSON-Datenpaket per POST-Request an deine hinterlegte WebHookUri .

Beispiel eines eingehenden Webhook-Requests

Eingehende Header:

POST /api/webhooks/incoming/custom
Content-Type: application/json
ms-signature: sha256-49F2B9346A7EE14F3261D76B050398713985FDFB9627CB3059BDEDAA1DC292E7
X-Custom-Header: MyValue

Payload (Body):

{
  "Id": "97a25f27-af57-4b99-9ec3-8234275275b8",
  "Attempt": 1,
  "Properties": { "SystemId": "Shop_01" },
  "Notifications": [
    {
      "Action": "order.updated",
      "BillBeeOrderId": 968619,
      "OrderNumber": "10001",
      "TotalCost": 23.80,
      "Currency": "EUR"
    }
  ]
}

Validierung der Signatur

Da deine Webhook-Adresse öffentlich erreichbar sein muss, könnte theoretisch jeder Daten an deinen Server senden. Um sicherzustellen, dass ein Request wirklich von Billbee stammt und nicht manipuliert wurde, musst du die Signatur prüfen.

Billbee nimmt hierzu den gesamten Inhalt des Request-Bodys und berechnet zusammen mit deinem hinterlegten Secret einen Hash-Wert (HMAC-SHA256). Dieser Wert wird im HTTP-Header ms-signature mitgeliefert.

Hier sind zwei Beispiele, wie du diese Validierung in deiner Anwendung umsetzen kannst:

Validierung in C# (.NET)

Nutzt du beispielsweise Microsoft.AspNet.WebHooks , kann die Validierung wie folgt aussehen:

using System.Security.Cryptography;

using System.Text;


public bool IsValid (string jsonBody, string incomingSignature, string secret)
{
    var keyBytes = Encoding.UTF8.GetBytes(secret);
    var bodyBytes = Encoding.UTF8.GetBytes(jsonBody);
    
    using var hmac = new HMACSHA256(keyBytes);
    var hash = hmac.ComputeHash(bodyBytes);
    
    var computedSignature = BitConverter.ToString(hash).Replace("-", "");
    
    return string.Equals(computedSignature, incomingSignature.Replace("sha256=", ""), StringComparison.OrdinalIgnoreCase);
}

Validierung in PHP

Für PHP-Entwickler:innen lässt sich die Prüfung wie folgt implementieren:

PHP

function isValid($jsonBody, $incomingSignature, $secret) {
    $incomingSignature = str_ireplace('sha256=', '', $incomingSignature);
    $computedSignature = hash_hmac('sha256', $jsonBody, $secret);
    
    return hash_equals(strtolower($computedSignature), strtolower($incomingSignature));
}

Wenn die berechnete Signatur mit der empfangenen Signatur übereinstimmt, ist das Datenpaket authentisch und sicher.