CEXT-2534: Documenting array-type field filtering

Author: ryanjcohen

src/pages/webhooks/hooks.md

@@ -134,6 +134,93 @@ The following example configures the webhook described above.
 </hook>
 ```
 
+If the default payload of a webhook contains an array of objects, use the following construction to select fields from that array:
+
+```text
+<object_name>[].<field_name>
+```
+
+For example, the payload of the `plugin.magento.quote.api.shipment_estimation.estimate_by_extended_address` event contains a top-level `results[]` array. The array contains details about two individual shipping estimates.
+
+```json
+{
+    "subject": [],
+    "result": [
+        {
+            "carrier_code": "tablerate",
+            "method_code": "bestway",
+            "carrier_title": "Best Way",
+            "method_title": "Table Rate",
+            "amount": 15,
+            "base_amount": 15,
+            "available": true,
+            "error_message": "",
+            "price_excl_tax": 15,
+            "price_incl_tax": 15
+        },
+        {
+            "carrier_code": "flatrate",
+            "method_code": "flatrate",
+            "carrier_title": "Flat Rate",
+            "method_title": "Fixed",
+            "amount": 20,
+            "base_amount": 20,
+            "available": true,
+            "error_message": "",
+            "price_excl_tax": 20,
+            "price_incl_tax": 20
+        }
+    ],
+    "cartId": "21",
+    "address": {
+        "street": "123 Test Road",
+        "city": "Test City",
+        "region_id": 12,
+        "region": "California",
+        "country_id": "US",
+        "postcode": "90000",
+        "firstname": "Test",
+        "lastname": "Test",
+        "company": "",
+        "telephone": "1800000000",
+        "save_in_address_book": 1,
+        "region_code": "CA",
+        "extension_attributes": []
+    }
+}
+```
+
+To transmit the `postcode` property of the `address` object and the `carrier_code`, `method_code`, and `base_amount` for each shipping estimate, the webhook's fields can be configured as follows:
+
+```xml
+<fields>
+    <field name='postcode' source='address.postcode' />
+    <field name='result[].carrier_code' />
+    <field name='result[].method_code' />
+    <field name='result[].base_amount' />
+</fields>
+```
+
+The following object would then be sent to the remote application:
+
+```json
+{
+    "postcode": "90000",
+    "result": [
+        {
+            "carrier_code": "tablerate",
+            "method_code": "bestway",
+            "base_amount": 15
+        },
+        {
+            "carrier_code": "flatrate",
+            "method_code": "flatrate",
+            "base_amount": 20
+        }
+    ]
+}
+```
+
 ### Field converters
 
 You can implement a converter class to convert a field to a different data type. For example, Commerce stores order IDs as numeric values. If the hook endpoint expects order IDs to be text values, you must convert the numeric value to a string representation before sending the payload.