Reduce the size of webhook requests
In some cases, the request payload from an Oracle Commerce webhook may be very large. This can cause performance issues, and external systems that impose size limits may reject the payload.
This section describes two ways 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 |
|
Order Submit |
|
Order Submit Without Payment Details |
|
Remorse Period Start |
|
Remorse Period Start Without Payment Details |
|
Shopper Profile Update |
|
Cart Idle |
|
Return Request Update |
|
Return Request Update Without Payment Details |
|
Account Create |
|
Account Update |
|
Request Quote |
|
Account Request |
|
Picked Up Items |
|
Order Cancel |
|
Order Cancel Without Payment Details |
|
Function Webhook | Truncatable Properties |
---|---|
Shipping Calculator |
|
Credit Card Payment |
|
External Price Validation |
|
Generic Payment |
|
External Tax Calculation |
|
Order Approvals |
|
Catalog and Price Group Assignment |
|
Custom Currency Payment |
|
Return Request Validation |
|
Return Request Validation Without Payment Details |
|
Order Qualification |
|
Order Validation |
|
External Promotions |
|
Cancel Order Update |
|
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 |
|
Account Update |
|
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"
}
],