Skip to main content
Skip table of contents

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.

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.

Frame 44 (1)-20250630-181647.png

  1. Navigate to the Fetch Event command of the Zendesk integration.

    Frame 42 (5)-20250630-175639.png
  2. Click on the Set Up Event Field Extraction Mapping button.

    Frame 41-20250630-175547.png
  3. Note the Main Event JSONPath expression (i.e., root context).

    Frame 2 (4)-20250630-175827.png
  4. 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
    Frame 45 (1)-20250630-183105.png
  5. Enable webhook authentication, then select the API Key option.

    Frame 39 (1)-20250630-183146.png

READER NOTE *

See API Key Authentication.

  1. Create an API key.

    Frame 47 (2)-20250630-185629.png
  2. Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.

    Frame 46 (2)-20250630-185035.png
  3. Send the POST request on Postman.

    Frame 48 (9)-20250630-190041.png
  4. Verify that an event was created in the Data Ingestion module.

    Frame 6 (1)-20250630-190128.png
  5. Note the eventId number.

    Frame 7 (1)-20250630-190217.png
  6. Navigate to the Investigation Dashboard page.

    Frame 49 (1)-20250630-190451.png
  7. Select the site in which the API key was generated in step 6.

    Frame 9 (1)-20250630-190521.png
  8. Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.

    Frame 10 (1)-20250630-190816.png
  9. Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

    Frame 50 (1)-20250630-191349.png
Example 2 - Bracket Notation

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

Frame 44 (1)-20250630-181647.png

  1. Navigate to the Fetch Event command of the Zendesk integration.

    Frame 42 (5)-20250630-175639.png
  2. Click on the Set Up Event Field Extraction Mapping button.

    Frame 41-20250630-175547.png
  3. Note the Main Event JSONPath expression (i.e., root context).

    Frame 2 (4)-20250630-175827.png
  4. 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']
    Frame 51 (2)-20250630-192514.png
  5. Enable webhook authentication, then select the API Key option.

    Frame 39 (1)-20250630-183146.png

READER NOTE *

See API Key Authentication.

  1. Create an API key.

    Frame 47 (2)-20250630-185629.png
  2. Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.

    Frame 46 (2)-20250630-185035.png
  3. Send the POST request on Postman.

    Frame 48 (9)-20250630-190041.png
  4. Verify that an event was created in the Data Ingestion module.

    Frame 56 (1)-20250630-193013.png
  5. Note the eventId number.

    Frame 57 (1)-20250630-193616.png
  6. Navigate to the Investigation Dashboard page.

    Frame 49 (1)-20250630-190451.png
  7. Select the site in which the API key was generated in step 6.

    Frame 9 (1)-20250630-190521.png
  8. Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.

    Frame 58 (3)-20250630-193905.png
  9. Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

    Frame 59 (1)-20250630-194123.png
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.

Frame 44 (1)-20250630-181647.png

  1. Navigate to the Fetch Event command of the Zendesk integration.

    Frame 42 (5)-20250630-175639.png
  2. Click on the Set Up Event Field Extraction Mapping button.

    Frame 41-20250630-175547.png
  3. Note the Main Event JSONPath expression (i.e., root context).

    Frame 2 (4)-20250630-175827.png
  4. 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']
    Frame 60 (2)-20250630-195443.png
  5. Enable webhook authentication, then select the API Key option.

    Frame 39 (1)-20250630-183146.png

READER NOTE *

See API Key Authentication.

  1. Create an API key.

    Frame 47 (2)-20250630-185629.png
  2. Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.

    Frame 46 (2)-20250630-185035.png
  3. Send the POST request on Postman.

    Frame 48 (9)-20250630-190041.png
  4. Verify that an event was created in the Data Ingestion module.

    Frame 62 (3)-20250630-195944.png
  5. Note the eventId number.

    Frame 61 (1)-20250630-200016.png
  6. Navigate to the Investigation Dashboard page.

    Frame 49 (1)-20250630-190451.png
  7. Select the site in which the API key was generated in step 6.

    Frame 9 (1)-20250630-190521.png
  8. Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.

    Frame 63 (2)-20250630-200157.png
  9. Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

    Frame 64 (1)-20250630-200333.png
Example 4 - Recursive Descent

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

Frame 44 (1)-20250630-181647.png

  1. Navigate to the Fetch Event command of the Zendesk integration.

    Frame 42 (5)-20250630-175639.png
  2. Click on the Set Up Event Field Extraction Mapping button.

    Frame 41-20250630-175547.png
  3. Note the Main Event JSONPath expression (i.e., root context).

    Frame 2 (4)-20250630-175827.png
  4. 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
    Frame 65 (1)-20250630-223922.png
  5. Enable webhook authentication, then select the API Key option.

    Frame 39 (1)-20250630-183146.png

READER NOTE *

See API Key Authentication.

  1. Create an API key.

    Frame 47 (2)-20250630-185629.png
  2. Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.

    Frame 46 (2)-20250630-185035.png
  3. Send the POST request on Postman.

    Frame 48 (9)-20250630-190041.png
  4. Verify that an event was created in the Data Ingestion module.

    Frame 66 (1)-20250630-224303.png
  5. Note the eventId number.

    Frame 67 (1)-20250630-224606.png
  6. Navigate to the Investigation Dashboard page.

    Frame 49 (1)-20250630-190451.png
  7. Select the site in which the API key was generated in step 6.

    Frame 9 (1)-20250630-190521.png
  8. Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.

    Frame 68 (1)-20250630-224740.png
  9. Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

    Frame 69 (1)-20250630-225037.png
Example 5 - Filter Expression

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

Frame 44 (1)-20250630-181647.png

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

  1. Navigate to the Fetch Event command of the Zendesk integration.

    Frame 42 (5)-20250630-175639.png
  2. Click on the Set Up Event Field Extraction Mapping button.

    Frame 41-20250630-175547.png
  3. Note the Main Event JSONPath expression (i.e., root context).

    Frame 2 (4)-20250630-175827.png
  4. 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
    Frame 76 (3)-20250702-201746.png
  5. Enable webhook authentication, then select the API Key option.

    Frame 39 (1)-20250630-183146.png

READER NOTE *

See API Key Authentication.

  1. Create an API key.

    Frame 47 (2)-20250630-185629.png
  2. Copy the request information to Postman, then select a preprocessing playbook under the Additional Settings accordion.

    Frame 46 (2)-20250630-185035.png
  3. Send the POST request on Postman.

    Frame 48 (9)-20250630-190041.png
  4. Verify that an event was created in the Data Ingestion module.

    Frame 77 (5)-20250702-202547.png
  5. Note the eventId number.

    Frame 78 (4)-20250702-202455.png
  6. Navigate to the Investigation Dashboard page.

    Frame 49 (1)-20250630-190451.png
  7. Select the site in which the API key was generated in step 6.

    Frame 9 (1)-20250630-190521.png
  8. Locate the event with an ID matching the one observed in step 10, then click on the event to view its details.

    Frame 79 (2)-20250702-202717.png
  9. Verify that the value extraction for the "target" field is displayed adjacent to the custom field configured in step 4.

    Frame 80 (1)-20250702-202858.png

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.

Frame 2 (3)-20250627-203139.png
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
Frame 81 (1)-20250702-233918.png

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.