Description:
Configuring KLS to communicate a loyalty event and data about the event to a 3rd party via their API requires a properly configured Webhook.
It is important to gain access to service provider documentation to understand their specific API implementation, as details vary from provider to provider. Two common formats for Web Services and APIs are SOAP/XML and REST-based which leverages the JSON format.
Likewise, the experienced KLS user first validates their webhook and authorization configuration in a tool such as POSTMAN to confirm their settings prior to configuring KLS.
Example 1: Simple Webhook with Basic Authorization and JSON-formatted Body
When a loyalty event that is configured to use this webhook occurs, a POST to the URL will fire. The request will include a single key/value pair in the header and content in a JSON-formatted body.
In this example, the {{memberEmail}} personalization variable will be replaced with the actual loyalty member email address value when the request is constructed.
Example - Body (JSON-format)
{
"OrderReferenceNumber": "UAT9834343",
"Recipient": {
"Email": "{{memberEmail}}",
"FirstName": "Bouny",
"LastName": "Mounarath",
"CompanyName": "DG",
"MobileNumber": "0430130258",
"PhoneNumber": "0411441441"
},
"DigitalStoreCardOrder": {
"PersonalisationInfo": {
"To": "",
"Message": "",
"From": ""
},
"OrderItems": [
{
"Quantity": 1,
"SKU": "AUDGADUXC002",
"ReferenceNumber": "UATkju034344",
"Amount": 50.0
}
]
}
}
Example 2: Simple Webhook with OAuth API Credentials and a Header Key/Value Pair
When a loyalty event that is configured to use this example webhook occurs, KLS obtains an access token via OAuth, then issues a PUT to the URL will fire, with the {{memberId}} personalization variable being replaced with the loyalty member ID value as a parameter value at runtime.
The request will include a single key/value pair in the header.
This particular example webhook does not require content in the request body.
Example 3: Webhook with OAuth API Credentials and Access Token Provider in Header
When a loyalty event that is configured to use this example webhook occurs, KLS obtains an access token via a specified OAuth configuration, then a GET to the URL will fire.
The request will pass along the just-obtained access token in the header when the {{webhook.accessToken}} personalization value is replaced at runtime.
This example webhook configuration does not require content in the request body.
Example 4: Webhook with Content-Type Key/Value Pair and XML-formatted Body
When a loyalty event that is configured to use this example webhook occurs, KLS issues a POST to the URL.
The request includes a single key/value pair in the header, and the body is composed in XML-format.
The body includes a static WSSecurityToken value for token-based authorization, and at runtime, the request body will include a personalization variable value for {{memberId}}.
Example Body (XML-format)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:loy="LoyaltyPlatformWS">
<soap:Header/>
<soap:Body>
<loy:SetMemberDescriptor>
<!--Optional:--> <loy:WSSecurityToken>e0h7J79mWYo0tW702X0r7hLK9LW21QB931bv9XOG3Ol23n4l</loy:WSSecurityToken>
<!--Optional:-->
<loy:MemberAccountId></loy:MemberAccountId>
<loy:SBInternalMemberId>{{memberId}}</loy:SBInternalMemberId>
<!--Optional:-->
<loy:MemberDescriptorExternalReference>MT</loy:MemberDescriptorExternalReference>
<loy:AddMemberToDescriptor>1</loy:AddMemberToDescriptor>
</loy:SetMemberDescriptor>
</soap:Body>
</soap:Envelope>
Example 5: Webhook with static Authorization Key/Value Pair
When a loyalty event that is configured to use this example webhook occurs, KLS issues a POST to the URL.
Two header key/value pairs are included in the request, specifying required Content-Type and Authorization values.
The JSON-formatted body includes a {{memberEmail}} personalization variable that will be replaced at runtime.
Example Body (JSON-format)
{
"subscription_group_id": "5f5b9-7d48-46f2-a1cd-d13a3bbc",
"subscription_state": "subscribed",
"external_id": "86",
"email": ["{{memberEmail}}"]
}
