Reduce the Size of Webhook Requests

In some cases, the request payload from an Retail Digital Commerce webhook may be very large. This can cause performance issues, and external systems that impose size limits may reject the payload.

This section applies to Open Storefront Framework (OSF).

This section describes two ways Retail Digital Commerce provides to reduce the size of certain webhook payloads:

Limit the number of items in payloads
Send changes rather than complete data

Limit the Number of Items in Payloads

You can configure webhooks to truncate certain properties in their request payloads. This capability is limited to specific Map and Collection properties, because these properties are the ones most likely to result in very large payloads. For example, the Shopper Profile Update webhook has two properties that can be truncated, secondaryAddresses and shippingAddresses.

To truncate these properties, you configure the webhook using endpoints in the Admin API, and set the value of subEntityTruncationSize to specify the maximum number of records to return for the property. (By default, the value of this setting is null, which means there is no limit.) You can set this property to an integer from 100 to 50000. For example, the following sets the threshold to 200:

PUT /ccadmin/v1/webhooks/production-updateProfile  HTTP/1.1

{
    "subEntityTruncationSize": 200
}

This means that if the secondaryAddresses or shippingAddresses property has 200 records or fewer, the addresses are included in the property as usual. But if one of these properties has 201 or more records, the property is omitted from the payload and is replaced with an indication that it has been truncated. In the following example, the shippingAddresses property has been truncated:

{
  "profileId": "110000",
  "profile": {
    ...
    "id": "110000",
    "shippingAddressesIsTruncated": true,
    ...
  },
  "siteId": "siteUS",
  "type": "atg.dps.ProfileUpdate"
}

The special property indicating that a property has been truncated is given the name of the truncated property with IsTruncated appended. So in this example, the name of the special property is shippingAddressesIsTruncated.

The external system that the webhook sends its payload to can take appropriate action when it receives indication that a property has been truncated. For example, the system could then make a call to the getProfile endpoint to get the addresses.

The following tables list the event webhooks and function webhooks that have properties whose values can be truncated:

Event Webhook	Truncatable Properties
Shopper Profile Create	secondaryAddresses shippingAddresses
Order Submit	commerceItems
Order Submit Without Payment Details	commerceItems
Remorse Period Start	commerceItems
Remorse Period Start Without Payment Details	commerceItems
Shopper Profile Update	secondaryAddresses shippingAddresses
Cart Idle	items childItems
Return Request Update	commerceItems returnItemList childReturnItems
Return Request Update Without Payment Details	commerceItems returnItemList childReturnItems
Account Create	allSecondaryAddresses secondaryAddresses
Account Update	allSecondaryAddresses secondaryAddresses
Request Quote	commerceItems
Account Request	secondaryAddresses
Picked Up Items	commerceItems
Order Cancel	commerceItems
Order Cancel Without Payment Details	commerceItems

Function Webhook	Truncatable Properties
Shipping Calculator	items childItems
Credit Card Payment	commerceItems
External Price Validation	items childItems
Generic Payment	commerceItems
External Tax Calculation	items childItems
Order Approvals	items childItems
Catalog and Price Group Assignment	items childItems allSecondaryAddresses secondaryAddresses shippingAddresses
Custom Currency Payment	commerceItems
Return Request Validation	commerceItems returnItemList childReturnItems
Return Request Validation Without Payment Details	commerceItems returnItemList childReturnItems
Order Qualification	items childItems
Order Validation	items childItems
External Promotions	items childItems
Cancel Order Update	commerceItems

Send Changes rather than Complete Data

Another option for reducing the size of webhook payloads is to include only the items that have been changed. This option is available for two event webhooks, Shopper Profile Update and Account Update, and applies to the properties listed in the table below:

Webhook	Properties
Shopper Profile Update	secondaryAddresses shippingAddresses loyaltyPrograms secondaryOrganizations siteProperties roles abandonedOrders secondaryAddresses.types shippingAddresses.types
Account Update	secondaryAddresses siteOrganizationProperties members relativeRoles ancestorOrganizations secondaryAddresses.types siteOrganizationProperties.shippingMethods

To enable this option for the Shopper Profile Update or Account Update webhook, you set the webhook's includeChangesOnly value to true. (The default is false.) For example:

PUT /ccadmin/v1/webhooks/production-updateProfile  HTTP/1.1

{
    "includeChangesOnly": true
}

If this option is enabled for one of these webhooks, the properties listed above will include the records that have been modified. Each modified object includes a special _actionCode property whose value indicates how the object has changed. Valid values are CREATE, UPDATE, and DELETE. In the following example, the shippingAddresses property includes only the addresses that have been changed:

The following is an example of the shippingAddresses property in the request:

"shippingAddresses": [
  {
    "country": "US",
    "lastName": "Anderson",
    "address3": "",
    "city": "Syracuse",
    "address2": "",
    "prefix": "",
    "address1": "21 Cedar Ave",
    "postalCode": "13202",
    "companyName": "",
    "county": "",
    "suffix": "",
    "firstName": "Kim",
    "externalAddressId": null,
    "phoneNumber": "212-555-1977",
    "item-id": null,
    "_actionCode": "UPDATE",
    "repositoryId": "se-980031",
    "faxNumber": "",
    "middleName": "",
    "state": "NY"
  },
  {
    "_actionCode": "DELETE",
    "repositoryId": "140010"
  }
],