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",
      "unique_id":"9893f0a0-2e90-4b73-9b3c-3f501f1a2d0c",
      "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",
      "unique_id":"9893f0a0-2e90-4b73-9b3c-3f501f1a2d0c",
      "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",
      "unique_id":"9893f0a0-2e90-4b73-9b3c-3f501f1a2d0c",
      "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",
      "unique_id":"9893f0a0-2e90-4b73-9b3c-3f501f1a2d0c",
      "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"
}