Benachrichtigungen Webhooks und Emails

Benachrichtigungen Webhooks

Events

Subscription

SubscriptionCreated

Abo wurde erstellt
Abo kann noch inaktiv sein
Abo kann sich noch im Trial-Modus befinden

SubscriptionActivated

Abo wurde gestartet (kein Trial/Trial beendet)
Abo wurde nach Pausierung fortgesetzt
Abo wurde nach Stornierung reaktiviert

SubscriptionUpdated

Abo wurde geändert (Addons oder Charges hinzugefügt/entfernt, Zahlungsweise geändert, Adressdaten geändert …)

SubscriptionPaused

Abo wurde pausiert, aber nicht storniert

SubscriptionCancelled

Abo wurde storniert

Item-Kauf

ItemPurchased

regulärer Artikel (kein Abo) gekauft

ItemCancelled

regulärer Artikel (kein Abo) storniert

Customer

CustomerUpdated

ein Kunde hat im Kundenportal seine E-Mail-Adresse geändert

Versand

Webhooks werden ausschließlich per HTTP POST an die hinterlegte URL versandt
- der Zielserver MUSS HTTPS (SSL) unterstützen und ein gültiges Zertifikat vorweisen
- unsichere URLs für Endpunkte (http://xxx) werden nicht akzeptiert
- fehlende oder ungültige SSL-Zertifikate lösen einen Fehlversuch des Webhooks aus
die mindestens einmalige Zustellung wird garantiert (Ausnahme bei 10 fehlgeschlagenen Zustellversuchen, s. o. “Fehler & Retries”)
die Zustellreihenfolge wird nicht garantiert

Topic-Zuordnung

jeder Webhook enthält einen X-Webhook-Topic-Header

Validierung

jeder Webhook enthält einen X-Webhook-Content-Hash-Header
der Hash wird aus der Payload (JSON-kodiert) und dem je Lieferant vergebenen Webhook-Secret als Key generiert (HMAC sha256)

Beispiel-Validierung:

// This assumes the received data has been cast to object/array beforehand by the
// used framework

$calculatedWebhookHash = hash_hmac('sha256', json_encode($receivedWebhookData), $vendorSecret);
$hashesMatch = hash_equals($calculatedWebhookHash, $receivedHashFromHeader);

// TRUE if calculated hash and hash received in X-Webhook-Content-Hash header match,

// FALSE otherwise

// If hashes do not match, the Webhook MUST be discarded

Fehler & Retries

antwortet der Empfängerserver nicht innerhalb von 5 Sekunden mit einem 200er-Statuscode, gilt der Versand als fehlgeschlagen
fehlgeschlagene Webhooks werden bis zu 10-mal erneut versandt, dabei erhöht sich mit jedem Versuch der Zeitabstand bis zum nächsten
- nach 5 Versuchen erhält der Lieferant eine E-Mail-Benachrichtung mit der Warnung, dass ein Webhook noch nicht zugestellt werden konnte
nach 10 fehlgeschlagenen Versuchen (ca. 3 Tage nach initialem Versand) gilt der Webhook als endgültig fehlgeschlagen und wird nicht erneut versendet
- der Lieferant wird per E-Mail über den nicht zustellbaren Webhook informiert

Versionierung

Webhooks sind über einen X-Webhook-Version-Header versioniert (aktuell: 1)
Lieferanten können die gewünschte Version wählen
bei Nutzung einer veralteten Version wird ein X-Webhook-Version-Deprecated-Header mitgesandt
veraltete Versionen werden nicht unendlich lang supported (Timeline TBD)
- vor Abschaltung wird mehrfach per E-Mail gewarnt und ein festes Datum der Abschaltung genannt

Payloads [v1]

Subscription-Events

{
	"order_id": "foo_order123",

	"payment_status": "paid",

	"contract_number": "23-1002243",
	"subscription": {

		"id": "foobar123",

		"status": "active",

		"billing_period": 1,

		"billing_period_unit": "month"

	},

	"plan": {

		"sku": "foo_subscription",

		"quantity": 8,

		"price": "150.00",

		"total": "1050.00",

		"discount": "10.00",

		"taxes": [

			{

				"name": "VAT",

				"rate": 19,

				"amount": "177.84"

			}

		],

		"free_quantity": 1,

		"currency": "EUR"

	},

	"addons": [],

	"parts_list_items" : [

		{

			0 : "SP-00015",

			1 : "SP-00136",

			...

		}

	],

	"previous_contract": {

		"number": "23-000012"

	},

	"discount_codes": [

		"foo_discount_10"

	],

	"customer": {

		"id": "foo_customer123",

		"first_name": "Foo",

		"last_name": "Bar",

		"email": "foo@bar.baz",

		"phone": null,

		"vat_id": null,

		"billing_address": {

			"company": null,

			"first_name": "Foo",

			"last_name": "Bar",

			"email": "foo@bar.baz",

			"phone": null,

			"street": "Foostreet 123",

			"address_addition": null, 
"zip_code": "12345",

			"city": "Foocity",

			"country": "DE"

		},

		"delivery_address": {

			"company": null,

			"first_name": "Foo",

			"last_name": "Bar",

			"email": "foo@bar.baz",

			"phone": null,

			"street": "Foostreet 123",

			"address_addition": null,

			"zip_code": "12345",

			"city": "Foocity",

			"country": "DE"

		}

	}

}

Item-Kauf-Events

{

	"order_id": "foo_order123",

	"contract_number": "23-1002243",

	"payment_status": "paid",

	"item": {

		"sku": "foo_item",

		"quantity": 8,

		"price": "150.00",

		"total": "1050.00",

		"discount": "10.00",

		"taxes": [

			{

				"name": "VAT",

				"rate": 19,

				"amount": "177.84"

			}

		],

		"free_quantity": 1,

		"currency": "EUR"

	},

	"addons":[],

	"parts_list_items" : [],

	"previous_contract": [],

	"discount_codes": [

		"foo_discount_10"

	],

	"customer": {

		"id": "foo_customer123",

		"first_name": "Foo",

		"last_name": "Bar",

		"email": "foo@bar.baz",

		"phone": null,

		"vat_id": null,

		"billing_address": {

			"company": null,

			"first_name": "Foo",

			"last_name": "Bar",

			"email": "foo@bar.baz",

			"phone": null,

			"street": "Foostreet 123",

			"address_addition": null,

			"zip_code": "12345",

			"city": "Foocity",

			"country": "DE"

		},

		"delivery_address": {

			"company": null,

			"first_name": "Foo",

			"last_name": "Bar",

			"email": "foo@bar.baz",

			"phone": null,

			"street": "Foostreet 123",

			"address_addition": null,

			"zip_code": "12345",

			"city": "Foocity",

			"country": "DE"

		}

	}

}

Customer-Events

{

	"customer_id": "9aa8b48a-c4d5-48a8-b230-5e9b0bfd5b05",

  "customer_name": "name",

  "customer_old_email": "old-mail@customer.de",

  "customer_email": "new-mail@customer.de",

}