INHALTSVERZEICHNIS

Overview

The purpose of this feature is to provide the clients with the possibility of setting up custom WebHooks linked to campaign state changes in order to report campaign and recipient information back into customers CRM.

When a campaign changes its state, e.g. from draft to live (campaign was booked) or print to live (handover to postal service), the system will trigger a request to a specific endpoint called with a specific payload.

A configured web hook is defined by:

triggering state transition
type of web hook (defines available data)
request target definition
payload template

State transitions

Most common used transitions are:

campaign was booked
campaign was reviewed successfully and print starts
campaign was handed over to postal service

Web Hook types

There are 4 different type of web hook available which are providing access to different data usable as request payload.

Campaign

Campaign web hook are triggered once per state change of the campaign and provide the following data:

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

Additional data regarding configured products within the campaign are available on request.

Variation

Variation web hook are triggered once for each variation defined in the campaign per state change of the campaign and provide the same data as for type Campaign except variationsCount plus:

variationId

All volume and pricing values are per variation.

Recipients

Recipients web hook are trigger for all recipients in multiple batches per state change of the campaign and provide the same data as for type Campaign (under prefix “campaign.”) plus the following data per recipient (array of objects in “recipients”):

  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

A batch size (how many recipients will be sent in 1 request) must be defined. For every triggered web hook request, the variable “recipients” will contain only the number of recipients as defined by batch size.

ExcludedCustomerAddress

ExcludedCustomerAddress web hook are trigger for all customer addresses which have not been included into the campaign due to validation errors or because they are flagged with a warning which was marked as “excluded”. Like Recipients they are triggered in multiple batches per state change of the campaign and provide the same data as for type Campaign (under prefix “campaign.”) plus the following data per excluded customer address (array of objects in “excludedCustomerAddress”):

  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

A batch size (how many excluded customer addresses will be sent in 1 request) must be defined. For every triggered web hook request, the variable “recipients” will contain only the number of excluded customer addresses as defined by batch size.

Supported request targets

SalesForce Marketing Cloud

The web hook triggers a request to the SFMC API for upserting data into a data extension. Authentication in SFMC API is controlled by optilyz.

The following information are required:

CustomerKey of the data extension to update
one or multiple data extension field names and the corresponding optilyz field (see list of provided data above) to be used to identify (lookup) the particular row to be updated
one or multiple data extension field names and the corresponding optilyz field (see list of provided data above) to be used for actually updating (setting) data

example:

Data Extension CustomerKey:

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

Lookup Fields:

data extension field name	optilyz field name	static value
subscriberKey	recipients.externalId
campaign		“reactivation”

Update Fields:

data extension field name	optilyz field name	static value
cost	campaign.pricing.total / campaign.volume
shopId	recipients.address.individualisation1
foo		“bar”

Emarsys

The web hook triggers a request with JSON payload to the Emarsys API. Authentication in Emarsys API is controlled by optilyz automatically, no specific headers are needed. All available calls according to Emarsys API documentation can be executed: https://dev.emarsys.com/v2/emarsys-developer-hub

The following information are required:

method - the https request method
- GET
- POST
- PUT
endpoint - the Emarsys API endpoint (e.g. “/contact”)
body template - the body of the request (data from the dataSource may be used) - only for methods POST and PUT

Additional optional information:

headers template - the custom headers that the request target endpoint may want to use (data from the dataSource may be used)
query-params template - the custom query variables that the client may want to use (data from the dataSource may be used)

AWS API Gateway

The web hook triggers a AWS API Gateway request with custom JSON payload.

The following information are required:

method - the https request method
- GET
- POST
- PUT
region - the AWS API Gateway region
endpoint - the AWS API Gateway endpoint URL
accessKey - the AWS API Gateway accessKey
secretKey - the AWS API Gateway secretKey
body template - the body of the request (data from the dataSource may be used) - only for methods POST and PUT

Additional optional information:

headers template - the custom headers that the request target endpoint may want to use (data from the dataSource may be used)
query-params template - the custom query variables that the client may want to use (data from the dataSource may be used)

REST

The web hook triggers a https request with custom JSON payload. Authentication has to be handled through headers and/or query params.

The following information are required:

method - the https request method
- GET
- POST
- PUT
url - the url of the request, HTTPS only
body template - the body of the request (data from the dataSource may be used) - only for methods POST and PUT

Additional optional information:

headers template - the custom headers that the request target endpoint may want to use (data from the dataSource may be used)
query-params template - the custom query variables that the client may want to use (data from the dataSource may be used)

Template examples

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}}" }

optilyz Webhooks

Overview

State transitions

Web Hook types

Campaign

Variation

Recipients

ExcludedCustomerAddress

Supported request targets

SalesForce Marketing Cloud

Emarsys

AWS API Gateway

REST

Template examples

Body template

Headers template

Query-params template

Related Articles