Source Field — Supported JSONPath Expressions

LAST UPDATED: JULY 04, 2025

In an event field mapping configuration, the source field—continuing from the root context defined by the Main Event JSON Path—specifies how to retrieve the desired data from the ingested payload. Because the payload is a JSON structure, it is useful to understand the types of JSONPath expressions that can be used for the source field.

Understanding JSONPath Traversal

Locating specific data within a JSON structure requires navigation through its hierarchical levels, including fields within objects and elements within arrays. This navigation process is referred to as traversal. A JSONPath expression is used to perform such traversal within the structure.

EXAMPLE

If the desired data is located at

NONE

$.a.b.c.d.e.f

and the Main Event JSON Path is configured to

CODE

$.a.b.c

then

$.a.b.c is the root context, the base from which all subsequent paths are evaluated.
.d.e.f is the relative path or source field path, the path evaluated relative to the root context to locate the desired data.

Supported JSONPath Expressions for the Source Field

Categories	Examples	Notes
Dot Notation	`.a.b.c` segment 1: `.a` segment 2: `.b` segment 3: `.c`	Each segment accesses a field nested within the previous one.
Bracket Notation	`['a']['b']`	–
Mixed Dot and Bracket Notation	`.a['b'].c` `['a'].b['c']`	–
Recursive Descent	`..b` `..a.b` `.a..b` `..a..b`	Extracts all matching fields located at different nesting levels. See example.
Filter Expression	`..[?(@.a=='aa')]` `..[?(@['a']==false)].b.c` `..[?(@.a[?(@=='aa')])]..b` `..[?(@.a.b!='bb')]..[?(@.c=='cc')]` `..[?(@.a > 0 && @.a <= 20)]..b`	Evaluates each item from the immediately preceding path step—whether from an array or object—against the condition inside `[?()]`, and returns the items for which the condition is true.

Worked Examples

JSON PAYLOAD

JSON

{
    "results": [
        {
            "url": "https://example.com/api/v2/organizations/133.json",
            "id": 133,
            "name": "org 133",
            "shared_tickets": false,
            "shared_comments": false,
            "external_id": null,
            "created_at": "2025-12-05T10:15:30Z",
            "updated_at": "2025-12-05T18:45:00Z",
            "domain_names": [
                "org domain 13",
                "org domain 3",
                "org domain 133"
            ],
            "details": "details 133",
            "notes": "notes 133",
            "group_id": 133,
            "tags": [
                "tag 13",
                "tag 3",
                "tag 133"
            ],
            "organization_fields": {
                "country": "canada",
                "org_type": "cybersecurity",
                "status": "established"
            },
            "result_type": "organization",
            "demo_key": {
                "layer2": {
                    "layer3": {
                        "layer4": {
                            "layer5": {
                                "target": "demo value 133"
                            }
                        }
                    }
                }
            }
        }
    ]
}

READER NOTE

Update the payload's id field in the following examples with a unique value prior to each webhook push test.

Example 1 - Dot Notation

OBJECTIVE – Demonstrate the use of dot notation to extract the "target" field from the ingested JSON payload.

Navigate to the Fetch Event command of the Zendesk integration.
Click on the Set Up Event Field Extraction Mapping button.
Note the Main Event JSONPath expression (i.e., root context).
Select the Event Source for Organization option within the dropdown, then add a new field with the following source field value:
CODE
```
.demo_key.layer2.layer3.layer4.layer5.target
```
Enable webhook authentication, then select the API Key option.

READER NOTE *

See API Key Authentication.

Create an API key.
Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.
Send the POST request on Postman.
Verify that an event was created in the Data Ingestion module.
Note the eventId number.
Navigate to the Investigation Dashboard page.
Select the site in which the API key was generated in step 6.
Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.
Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

Example 2 - Bracket Notation

OBJECTIVE – Demonstrate the use of bracket notation to extract the "target" field from the ingested JSON payload.

Navigate to the Fetch Event command of the Zendesk integration.
Click on the Set Up Event Field Extraction Mapping button.
Note the Main Event JSONPath expression (i.e., root context).
Select the Event Source for Organization option within the dropdown, then add a new field with the following source field value:
CODE
```
['demo_key']['layer2']['layer3']['layer4']['layer5']['target']
```
Enable webhook authentication, then select the API Key option.

READER NOTE *

See API Key Authentication.

Create an API key.
Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.
Send the POST request on Postman.
Verify that an event was created in the Data Ingestion module.
Note the eventId number.
Navigate to the Investigation Dashboard page.
Select the site in which the API key was generated in step 6.
Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.
Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

Example 3 - Mixed Dot and Bracket Notation

OBJECTIVE – Demonstrate the mix use of dot and bracket notation to extract the "target" field from the ingested JSON payload.

Navigate to the Fetch Event command of the Zendesk integration.
Click on the Set Up Event Field Extraction Mapping button.
Note the Main Event JSONPath expression (i.e., root context).
Select the Event Source for Organization option within the dropdown, then add a new field with any of the following sample source field values:
SAMPLE 1
CODE
```
.demo_key.layer2['layer3']['layer4'].layer5['target']
```
SAMPLE 2
CODE
```
['demo_key'].layer2.layer3['layer4']['layer5'].target
```
SAMPLE 3
CODE
```
.demo_key['layer2'].layer3['layer4'].layer5['target']
```
Enable webhook authentication, then select the API Key option.

READER NOTE *

See API Key Authentication.

Create an API key.
Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.
Send the POST request on Postman.
Verify that an event was created in the Data Ingestion module.
Note the eventId number.
Navigate to the Investigation Dashboard page.
Select the site in which the API key was generated in step 6.
Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.
Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

Example 4 - Recursive Descent

OBJECTIVE – Demonstrate the use of recursive descent to extract the "target" field from the ingested JSON payload.

Navigate to the Fetch Event command of the Zendesk integration.
Click on the Set Up Event Field Extraction Mapping button.
Note the Main Event JSONPath expression (i.e., root context).
Select the Event Source for Organization option within the dropdown, then add a new field with any of the following sample source field values:
SAMPLE 1
CODE
```
..target
```
SAMPLE 2
CODE
```
..layer5.target
```
SAMPLE 3
CODE
```
.demo_key..target
```
SAMPLE 4
CODE
```
..layer2..target
```
Enable webhook authentication, then select the API Key option.

READER NOTE *

See API Key Authentication.

Create an API key.
Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.
Send the POST request on Postman.
Verify that an event was created in the Data Ingestion module.
Note the eventId number.
Navigate to the Investigation Dashboard page.
Select the site in which the API key was generated in step 6.
Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.
Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

Example 5 - Filter Expression

OBJECTIVE – Demonstrate the use of various filter expressions to extract the "target" field from the ingested JSON payload.

EXPRESSION RESTRICTION

Fields above the level of the filtered array item cannot be retrieved.
INVALID EXAMPLES
🚫 ..[?(@.target == 'value A2')].name
🚫 ..[?(@.target == 'value A2')].notes
🚫 ..[?(@.target == 'value A2')].group_id

Navigate to the Fetch Event command of the Zendesk integration.
Click on the Set Up Event Field Extraction Mapping button.
Note the Main Event JSONPath expression (i.e., root context).

Select the Event Source for Organization option within the dropdown, then add seven fields with the following source field values:
DEMO FIELD 1 (returns an object)

CODE

..[?(@.target == 'demo value 133')]

DEMO FIELD 2

CODE

..[?(@.target == 'demo value 133')].target

DEMO FIELD 3 (returns an object with nested objects)

CODE

..[?(@['layer4'].layer5['target'] == 'demo value 133')]

DEMO FIELD 4

CODE

..[?(@.shared_tickets==false)].demo_key.layer2.layer3.layer4.layer5.target

DEMO FIELD 5

CODE

..[?(@.tags[?(@=='tag 133')])]..target

DEMO FIELD 6

CODE

..[?(@organization_fields.country=='canada')]..target

DEMO FIELD 7 (returns an object)

CODE

..[?(@.organization_fields.country!='usa')]..[?(@.target=='demo value 133')]

DEMO FIELD 8

CODE

..[?(@.group_id >= 100 && @.group_id < 200)]..target

Enable webhook authentication, then select the API Key option.

READER NOTE *

See API Key Authentication.

Create an API key.
Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.
Send the POST request on Postman.
Verify that an event was created in the Data Ingestion module.
Note the eventId number.
Navigate to the Investigation Dashboard page.
Select the site in which the API key was generated in step 6.
Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.
Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

FAQ

Where can users configure the Main Event JSONPath expression?

The Main Event JSON Path, configured in (Default Event Source) > Edit Event Source, defines the root context from which individual source fields are resolved.

Why does the user receive an "Invalid JSON path expression" message?

Possible syntax errors include:

Unmatched brackets
- Example error: ..[?(@.group_id==133]
- Should be: ..[?(@.group_id==133)]
Missing or incorrect use of quotes
- Example error: ..[?(@.name==org 133)]
- Should be: ..[?(@.name=='org 133')]
Incorrect logical operator syntax
- Example error: ..[?(@.group_id=133)]
- Should be: ..[?(@.group_id==133)]
Trailing or misplaced dots
- Example error: .name.
- Should be: .name
Incorrect recursive descent placement
- Example error: [..target]
- Should be: ..target
Missing Square Filter Brackets
- Example error: ..?(@.group_id==133)
- Should be: ..[?(@.group_id==133)]

Why does the user not see their custom fields in the Event Details popover?

Possible reasons (in reference to the sample payload) include:

Absent source field in ingested data
- Example error: ..non_existent_field
- Sample fix: ..target
Source field points to a null, empty string, empty object, or empty array
- Example error: .external_id (a null value)
Incorrect assumption of square-bracket prefix when the Main Event JSONPath is an array
- Example error: [*]..target
- Sample fix: ..target
Incorrect path context
- Example error: ..[?(@.group_id)].target
  - The target field is a not direct child of the object containing group_id
- Sample fix: ..[?(@.group_id)]..target
Incorrect application of filter
- The filter expression [?()] applies to only arrays, not single objects.
- Example error: ..layer4[?(@.target=='demo value 133')]
  - This expression applies a filter to layer4, which is an object, not an array.
- Sample fix: ..layer4.layer5.target

What does extracting targets at every depth using recursive descent mean?

SAMPLE INGESTED DATA

JSON

{
    "results": [
        {
            "id": 74,
            "result_type": "organization",
            "name": "org A",
            "demo_key": {
                "layer2": {
                    "target": "value A1",
                    "layer3": {
                        "layer4": {
                            "target": "value A2"
                        }
                    }
                }
            }
        }
    ]
}

Using the source field ..target

the output will be:

CODE

value A1, value A2

READER NOTE

JSON does not permit duplicate field names within the same level of an object.

EXAMPLE – Consider the sample ingested data modified to the following structure:

JSON

{
  ...
  "layer2": {
    "target": "value A1",
    "target": "value A2"
  }
  ...
}

In this case, if ..target was used as the source field path, the second "target" key will overwrite the first during parsing.