Webhook Einstellungen

Was ist ein Webhook

Ein Webhook stellt die Möglichkeit dar, aus billware heraus, bei einem bestimmten Event, ein externes Script (bzw. Endpunkt) aufzurufen. Ein Webhook kann als ein "Event-Listener" oder als eine "Push-Notification" betrachtet werden.

Beispiel
 

Du hast einen Webhook angelegt, der bei dem Event order.create Deinen eigenen externen Endpunkt https://www.meine-domain.de/webhook anspricht. Jedes Mal, wenn jetzt in billware ein Auftrag angelegt wird, schickt der Webhook den gesamten Datensatz an den definierten Endpunkt. Dort kannst du die Daten weiterverarbeiten (z.B. ein Versand von Serial-Keys an Deinen Kunden etc.)

Webhook erstellen und konfigurieren

Verfügbare Optionen

Option Beschreibung
Status aktiviert / deaktiviert den Webhook.
Name Individueller Name für den Webhook.
Event Bei welchem Event (s. unten) der Webhook den Endpunkt ansprechen soll.
Endpunkt Der Endpunkt / das Skript, welches durch den Webhook angesprochen wird. Bitte beachten: Der Endpunkt muss mit https://.
Schlüssel Der geheime Schlüssel (bzw. Webhook-Secret), mit dessen Hilfe die Signatur erzeugt wird (s. Verifizierung).
Verzögerung Der Webhook kann mit einer Verzögerung abgeschickt werden. Mögliche Werte: zwischen 0 und 96 Stunden.
Zusätzliche Daten Der Webhok kann zusätzliche Daten im Format "Key => Value" transportieren. Diese Daten sind optional.

Verfügbare Events

Event Beschreibung
order.create Bei Neuanlegung eines Auftrags.
order.update Bei Aktualisierung eines bestehenden Auftrags.
order.delete Bei Löschung eines Auftrags.
customer.create Bei Neuanlegung eines Kunden.
customer.update Bei Aktualisierung eines bestehenden Kunden.
customer.delete Bei Löschung eines Kunden.
article.create Bei Neuanlegung eines Artikels.
article.update Bei Aktualisierung eines bestehenden Artikels.
article.delete Bei Löschung eines Artikels.

Header

Es werden mit jedem Webhook zwei HTTP-Header mitgeschickt:

X-Bw-Signature: Enthält die Signatur, die aus den geschickten Daten und dem Schlüssel (Webhook-Secret) durch einen HMAC mit sha256 erzeugt wird.

X-Bw-Event: Enthält das Event (s. verfügbare Events).

Endpunkt-Verifizierung

PHP 

<?php
define('WEBHOOK_SECRET_KEY', 'my-secret-key');

function isFromBillware($data, $signature) {
	$calculated = base64_encode(hash_hmac('sha256', $data, WEBHOOK_SECRET_KEY, true));
	return $signature == $calculated;
}

$header = getallheaders();
$signature = $header['X-Bw-Signature'];
$data = file_get_contents('php://input');
if (isFromBillware($data, $signature)) {
	// do something
}
?>

Node.Js 

/*jshint node: true */
'use strict';

var crypto = require('crypto'),
config = require('../lib/config').config;

module.exports = function(secret) {
    return function(req, res, next) {
        req.isFromBillware = false;

        var bwSignature = req.header('X-Bw-Signature');
        if (bwSignature) {
            req.bwHasher = crypto.createHmac('sha256', secret);
            req.on('data', function (chunk) {
                req.bwHasher.update(chunk);
            });
            req.on('end', function() {
                var hash = req.bwHasher.digest('base64');
                req.isFromBillware = hash === bwSignature ? true : false;
            });
        }
        next();
    };
};

Hinweise

  • Ein Webhook-Endpoint kann nur über https:// angesprochen werden.
  • Jeder Webhook benötigt einen individuellen Schlüssel.
  • billware überprüft ob ein Webhook erfolgreich war, wenn ein HTTP-Status Code zwischen 200 und 299 zurückgegeben wurde.
  • Der HTTP-Status Code 410 deaktiviert den Webhook.
  • Jeder HTTP-Status Code, der nicht zwischen 200 und 299 liegt oder 410 ist, stellt einen Fehler im Endpunkt dar. Der Webhook versucht bis zu 10 Mal (mit einem zeitlich ansteigendem Intervall) den Endpunkt zu kontaktieren. Nach 10 erfolglosen Versuchen, wird der Webhook deaktiviert.