optilyz Webhooks : Automated Direct Mail - HelpCenter

optilyz Webhooks

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/docs/core-api-reference

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:

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:

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