optilyz Webhooks

Überblick

Mit dieser Funktion erhalten Kunden die Möglichkeit, benutzerdefinierte Webhooks einzurichten, die bei Änderungen des Kampagnenstatus ausgelöst werden um Kampagnen- und Empfängerinformationen an das CRM des Kunden zurückzumelden.

Wenn sich der Status einer Kampagne ändert, z. B. von Draft zu Booked (Kampagne wurde gebucht) oder Print zu Live (Übergabe an die Post) führt das System API-Call an einen konfigurierten Endpunkt aus, der mit einer bestimmten Payload (= zu übertragende Daten) aufgerufen wird.

Ein Web-Hook wird definiert durch:

• Auslösender Statusübergang
• Art des Web-Hooks (definiert die für die Übertragung verfügbaren Daten)
• Ziel (Endpunkt) der API-Calls
• Zu übertragende Daten (Payload Template)

Statusübergänge

Die am häufigsten verwendeten Übergänge sind:

• Kampagne wurde gebucht
• Kampagne wurde erfolgreich überprüft und der Druckvorgang gestartet
• Kampagne wurde an die Post übergeben

Web-Hook-Arten

Es stehen 4 verschiedene Arten von Web-Hooks zur Verfügung, die den Zugriff auf verschiedene Daten ermöglichen, die als Payload verwendet werden können.

Campaign

Der Campaign-Web-Hook wird einmal pro Statusänderung der Kampagne ausgelöst und liefert die folgenden Daten:

name
state
type
accountName
accountConnectionType
countryName
countryCode
createdDate
createdWeek
createdMonth
bookingDate
bookingWeek
bookingMonth
postalHandoverDate
postalHandoverWeek
postalHandoverMonth
variationsCount
productsCount
hasEnvelope
volume
customerAddressVolume
controlAddressVolume
volumePerVariation
customerAddressVolumePerVariation
controlAddressVolumePerVariation
pricing.print
pricing.postage
pricing.premiumValidation
pricing.total
pricing.vatRate
pricing.vat
pricing.gross

Zusätzliche Daten zu konfigurierten Produkten innerhalb der Kampagne sind auf Anfrage verfügbar.

Variation

Der Variation-Web-Hook wird einmal für jede in der Kampagne definierte Variation pro Statusänderung der Kampagne ausgelöst und liefert dieselben Daten wie für den Typ "Campaign" mit Ausnahme von

variationsCount

Zusätzlich verfügbare Daten:

variationId

Alle Volumen- und Preiswerte verstehen sich pro Variation.

Recipients

Der Recipients-Web-Hook wird einmal pro Statusänderung der Kampagne ausgelöst und liefert dieselben Daten wie für den Typ Campaign (unter dem Präfix "Campaign") sowie die folgenden Daten (Array von Objekten in "recipients") pro Empfänger:

  variationIndex
  vouchers.code
  vouchers.itemIndex
  vouchers.voucherIndex
  externalId
  lineNumber
  addressSource.origin
  addressSource.sourceRef
  changes
  warns.field
  warns.message
  errs.field
  errs.message
  address.companyName1
  address.companyName2
  address.companyName3
  address.title
  address.otherTitles
  address.jobTitle
  address.gender
  address.firstName
  address.lastName
  address.fullName
  address.careOf
  address.street
  address.houseNumber
  address.address1
  address.address2
  address.address3
  address.zipCode
  address.city
  address.country
  address.individualisations

Die Empfänger werden hier in Batches prozessiert und somit ggf. mehrere API-Calls ausgeführt. Dazu muss eine Batchgröße (wie viele Empfänger in einem API-Call gesendet werden) definiert werden. Für jeden ausgelösten API-Call enthält die Variable "recipients" nur die Anzahl der Empfänger, wie durch die Batchgröße definiert. Für einen solchen Web-Hook werden also "Anzahl Empfänger / Batchgröße" API-Calls ausgeführt.

ExcludedCustomerAddress

ExcludedCustomerAddress-Webhooks werden für alle Kundenadressen ausgelöst, die aufgrund von Validierungsfehlern oder weil sie mit einer "excluded"-Warnung gekennzeichnet sind, nicht in die Kampagne aufgenommen wurden. Wie Empfänger werden sie in mehreren Batches pro Statusänderung der Kampagne ausgelöst und liefern dieselben Daten wie für den Typ Campaign (unter dem Präfix "Campaign") sowie die folgenden Daten (Array von Objekten in "excludedCustomerAddress") pro ausgeschlossener Kundenadresse:

  address.addressNameCounter
  address.jobTitle
  address.title
  address.otherTitles
  address.gender
  address.firstName
  address.lastName
  address.fullName
  address.companyName1
  address.companyName2
  address.companyName3
  address.individualisations
  address.street
  address.houseNumber
  address.careOf
  address.zipCode
  address.city
  address.country
  address.address1
  address.address2
  address.address3
  individualVouchers.code
  individualVouchers.columnName
  variationIndex
  externalId
  lineNumber
  addressSource.origin
  addressSource.sourceRef
  changes
  warns.field
  warns.message
  errs.field
  errs.message

Eine Batchgröße (wie viele ausgeschlossene Kundenadressen in einer Anfrage gesendet werden) muss definiert werden. Für jede ausgelöste Webhook-Anforderung enthält die Variable "Recipients" nur die Anzahl der ausgeschlossenen Kundenadressen, wie durch die Batchgröße definiert.

Unterstützte Ziel-Arten

SalesForce Marketing Cloud

Der Web-Hook löst einen Aufruf an die SFMC-API zum "Upserting" von Daten in eine Data Extension aus. Die Authentifizierung in der SFMC-API wird von optilyz gesteuert.

Folgende Informationen sind erforderlich:

• CustomerKey der zu aktualisierenden Data Extension
• ein oder mehrere Data Extension Feldernamen und das entsprechende optilyz-Feld (siehe Liste der bereitgestellten Daten oben), die zum Identifizieren (lookup) der bestimmten zu aktualisierenden Zeile verwendet werden sollen (wird eine solche Zeile nicht gefunden, wird sie erstellt)
• ein oder mehrere Data Extension Feldernamen und das entsprechende optilyz-Feld (siehe Liste der bereitgestellten Daten oben), die zum tatsächlichen Aktualisieren von Daten verwendet werden sollen

Beispiel:

Data Extension CustomerKey:

"988050E5-C613-4A91-841E-31B339C4297F"

Lookup Felder:

Update Felder:

Emarsys

Der Web-Hook löst eine Aufruf an die Emarsys-API aus. Die Authentifizierung in der Emarsys-API wird von optilyz automatisch gesteuert, es sind dazu keine spezifischen Header erforderlich. Alle verfügbaren Aufrufe gemäß der Emarsys API-Dokumentation können ausgeführt werden: https://dev.emarsys.com/docs/core-api-reference

Folgende Informationen sind erforderlich:

• method - https request-Methode:
  • GET
  • POST
  • PUT
• endpoint - der Emarsys API-Endpunkt (z. B. "/contact")
• body template - der body der request (Daten aus dataSource dürfen verwendet werden) - nur für die Methoden POST und PUT

Zusätzliche optionale Informationen:

• headers template - Die benutzerdefinierten Header, die der API-Call benötigt (Daten aus dataSource dürfen verwendet werden)
• query-params template - Die benutzerdefinierten Query-Parameter, die der API-Call benötigt (Daten aus dataSource dürfen verwendet werden)

AWS API Gateway

Der Web-Hook löst einen API-Call (REST) an einen AWS API Gateway-Endpunkt mit benutzerdefinierten JSON-Nutzdaten aus.

Folgende Informationen sind erforderlich:

• method - https request-Methode:
  • GET
  • POST
  • PUT
• region - die AWS-Region, in der der AWS API Gateway-Endpoint liegt
• endpoint - die AWS API Gateway-Endpoint URL
• accessKey - die AWS accessKey
• secretKey - die AWS secretKey
• body template - der body des Request (Daten aus dataSource dürfen verwendet werden) - nur für die Methoden POST und PUT

Zusätzliche optionale Informationen:

REST

Der Web-Hook löst einen HTTPS-API-Call (REST) mit benutzerdefinierten JSON-Nutzdaten aus. Die Authentifizierung muss über Header und / oder Query-Parameter erfolgen.

Folgende Informationen sind erforderlich:

• method - https request-Methode:
  • GET
  • POST
  • PUT
• url - Request-Endpoint-URL, nur HTTPS
• body template - der body des Request (Daten aus dataSource dürfen verwendet werden) - nur für die Methoden POST und PUT

Zusätzliche optionale Informationen:

Template Beispiele

Body Template

{
    "campaign": {
      "name": "{{campaign.name}}",
      "accountName": "{{campaign.accountName}}",
      "countryName": "{{campaign.countryName}}",
      "countryCode": "{{campaign.countryCode}}",
      "createdDate": "{{campaign.createdDate}}",
      "bookingDate": "{{campaign.bookingDate}}",
      "postalHandoverDate": "{{campaign.postalHandoverDate}}",
      "variationsCount": "{{campaign.variationsCount}}",
      "productsCount": "{{campaign.productsCount}}",
      "hasEnvelope": "{{campaign.hasEnvelope}}",
      "volume": "{{campaign.volume}}",
      "pricing_print": "{{campaign.pricing.print}}",
      "pricing_postage": "{{campaign.pricing.postage}}",
      "pricing_premiumValidation": "{{campaign.pricing.premiumValidation}}",
      "pricing_total": "{{campaign.pricing.total}}",
      "pricing_vat": "{{campaign.pricing.vat}}",
      "pricing_gross": "{{campaign.pricing.gross}}",
      "vatRate": "{{campaign.pricing.vatRate}}"
    },
    "recipients": [\
      {{#each recipients}}\
        {\
          "CUSTOMER_ID": "{{address.individualisations.[0]}}",\
          "SHOP_ID" : "{{address.individualisations.[1]}}",\
          "USERID" : "{{address.individualisations.[2]}}",\
          "variationIndex": "{{variationIndex}}",\
          "lineNumber": "{{lineNumber}}",\
          "sourceRef": "{{addressSource.sourceRef}}",\
          "warns": [\
            {{#each warns}}\
              {\
                "field": "{{field}}",\
                "message": "{{message}}"\
              }\
              {{#unless @last}},{{/unless}}\
            {{/each}}\
          ]\
        }\
        {{#unless @last}},{{/unless}}\
      {{/each}}\
    ],
    "excludedCustomerAddresses": [\
      {{#each excludedCustomerAddresses}}\
        {\
          "CUSTOMER_ID": "{{address.individualisations.[0]}}",\
          "SHOP_ID" : "{{address.individualisations.[1]}}",\
          "USERID" : "{{address.individualisations.[2]}}",\
          "variationIndex": "{{variationIndex}}",\
          "lineNumber": "{{lineNumber}}",\
          "sourceRef": "{{addressSource.sourceRef}}",\
          "warns": [\
            {{#each warns}}\
              {\
                "field": "{{field}}",\
                "message": "{{message}}"\
              }\
              {{#unless @last}},{{/unless}}\
            {{/each}}\
          ],\
          "errs": [\
            {{#each errs}}\
              {\
                "field": "{{field}}",\
                "message": "{{message}}"\
              }\
              {{#unless @last}},{{/unless}}\
            {{/each}}\
          ]\
        }\
        {{#unless @last}},{{/unless}}\
      {{/each}}\
    ]
  }

Headers Template

{ "Authorization": "Basic abc123" }

Query-params Template

{ "countryName": "{{countryName}}", "bookingMonth": "{{bookingMonth}}" }