Request

Response

    Callback Filtering

    A filter is a condition you attach to a webhook so that you are notified only when the event payload matches it. The event still occurs in the Autodesk service, and the webhook still matches it, but if the payload does not satisfy the filter, no callback is sent to your callback URL.

    Filtering does not change the product event, when it fires, or what the Autodesk service does with it. It only decides whether the Webhooks service calls you about it.

    When to Use a Filter

    Use a filter when your webhook is scoped correctly but still notifies you about more than you act on:

    • React only to payloads in a particular state or with a particular value. For example, notify me only when a translation failed, rather than on every completed translation.
    • Narrow notifications to the changes that matter. For example, notify me only about one file type in a folder that contains many.
    • Reduce unnecessary callback processing. A callback you never receive is one your server does not have to authenticate, verify, queue, and discard.

    A filter is a payload condition, so it is the right tool when the distinction you care about is in the data. If the distinction is which data, use the scope of the webhook instead. See Basics.

    How Filtering Works

    • The filter is a JsonPath expression stored in the filter field of the webhook. It is defined in JsonPath format.
    • It is evaluated against the payload of the callback. In a filter expression, $ refers to the contents of the payload field of the callback body, not the whole body. This is why the expression $[?(@.ext=='txt')] matches the field payload.ext.
    • It is evaluated per event. Each time the event occurs, the Webhooks service evaluates the filter against that event’s payload. If the expression matches, the callback is sent. If it does not, the callback is not sent.
    • You can set it when you create the webhook, and change it later. filter is accepted by the create operation and by the Update a Webhook operation, so you can tighten or loosen a filter without recreating the subscription.

    Filter Formats

    Single filter. One JsonPath expression in the filter field:

    "filter": "$[?(@.ext=='txt')]"
    

    Multiple filters. A list of JsonPath expressions, all of which must match for the callback to be sent:

    "filter": ["$[?(@.sizeInBytes>=1048576)]", "$[?(@.ext=='f3d')]"]
    

    The list form is an AND across expressions. To express OR, or to mix AND and OR, use the operators inside a single expression, as in Example 3 below.

    Writing a Filter

    1. Identify the event you subscribe to. Filter fields are payload fields, and each event defines its own payload.
    2. Inspect that event’s payload. Open the reference page for the event under Supported Events and look at the example body. The fields inside payload are the fields you can filter on.
    3. Choose the condition. Pick the field and the value that distinguish the callbacks you want from the ones you do not.
    4. Create the webhook with the filter field, or add the filter to an existing webhook with the Update a Webhook operation.
    5. Trigger the event in the Autodesk service, both in a way that should match and in a way that should not.
    6. Verify. Confirm your callback receives the matching case and does not receive the non-matching one. Testing only the matching case does not tell you whether the filter is doing anything at all.

    You can test a JsonPath expression against a sample payload before you use it, with a JsonPath evaluator such as jsonpath.herokuapp.com.

    Examples

    Example 1: Filter by File Extension

    Notify me only when the file added is a .txt file. This filters dm.version.added on the ext field of the payload.

    curl -X 'POST'\
         -v 'https://developer.api.autodesk.com/webhooks/v1/systems/data/events/dm.version.added/hooks'\
         -H 'Content-Type: application/json'\
         -H 'authorization: Bearer <ACCESS_TOKEN>'\
         -d '{
                "callbackUrl": "https://myapp.example.com/callback",
                "scope": {
                     "folder": "urn:adsk.wipprod:fs.folder:co.wT5lCWlXSKeo3razOfHJAw"
                },
                "filter": "$[?(@.ext=='txt')]"
          }'
    
    Show More

    A callback is sent for a payload like the following, abridged to the fields that matter here, because ext is txt:

    {
      "version": "1.0",
      "resourceUrn": "urn:adsk.wipprod:fs.file:vf.0zvdp3CoTzWDcZC_wL0kJA?version=1",
      "hook": {
        "system": "data",
        "event": "dm.version.added",
        "filter": "$[?(@.ext=='txt')]"
      },
      "payload": {
        "ext": "txt",
        "name": "notes.txt",
        "sizeInBytes": 36,
        "lineageUrn": "urn:adsk.wipprod:dm.lineage:0zvdp3CoTzWDcZC_wL0kJA"
      }
    }
    
    Show More

    A file added to the same folder with "ext": "rvt" does not match, so no callback is sent for it. The event itself still occurred.

    Example 2: Filter by a Set of Values

    Notify me only when a translation ended in failure or timed out. This filters extraction.finished on a nested field, using the in operator.

    curl -X 'POST'\
         -v 'https://developer.api.autodesk.com/webhooks/v1/systems/derivative/events/extraction.finished/hooks'\
         -H 'Content-Type: application/json'\
         -H 'authorization: Bearer <ACCESS_TOKEN>'\
         -d '{
                "callbackUrl": "https://myapp.example.com/callback",
                "scope": {
                     "workflow": "my-workflow-id"
                },
                "filter": "$[?(@.Payload.status in ['failed','timeout'])]"
          }'
    
    Show More

    The matching payload:

    {
      "version": "1.0",
      "resourceUrn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6d2htZHRlc3RzdGcvQ2FzZUlubmVyLmlwdA",
      "payload": {
        "TimeStamp": 1513134729128,
        "EventType": "EXTRACTION_FINISHED",
        "Payload": {
          "status": "failed",
          "scope": "7dca556c-e041-444a-91cf-cdea18a7699e",
          "registerKey": []
        }
      }
    }
    
    Show More

    Note the two levels of payload here. The lower-case payload is the callback envelope, which $ refers to. The capitalised Payload is a field defined by this event, which is why the expression reads @.Payload.status. This is a good illustration of why you should read the event’s own reference page rather than assume a shape.

    Example 3: Combine Conditions

    Notify me when the extraction finished and failed, or when the register key contains a particular name. This uses AND (&&) and OR (||) in one expression, and addresses an array with a wildcard.

    curl -X 'POST'\
         -v 'https://developer.api.autodesk.com/webhooks/v1/systems/derivative/events/extraction.finished/hooks'\
         -H 'Content-Type: application/json'\
         -H 'authorization: Bearer <ACCESS_TOKEN>'\
         -d '{
                "callbackUrl": "https://myapp.example.com/callback",
                "scope": {
                     "workflow": "my-workflow-id"
                },
                "filter": "$[?((@.EventType == 'EXTRACTION_FINISHED' && @.Payload.status == 'failed') || 'test123' in @.Payload.registerKey[*].name)]"
          }'
    
    Show More

    The matching payload:

    {
      "version": "1.0",
      "resourceUrn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6d2htZHRlc3RzdGcvQ2FzZUlubmVyLmlwdA",
      "payload": {
        "TimeStamp": 1513134729128,
        "EventType": "EXTRACTION_FINISHED",
        "Payload": {
            "status": "failed",
            "scope": "7dca556c-e041-444a-91cf-cdea18a7699e",
            "registerKey": [{
              "name": "test123"
            }]
        }
      }
    }
    
    Show More

    Expressions to Use

    The following JsonPath constructs appear in the documented filter examples above:

    ConstructMeaning
    $ The root, which is the contents of the callback’s payload field.
    @ The node currently being evaluated.
    [?( ... )] A filter expression. The callback is sent when it evaluates to true.
    .field.subfield Navigate to a nested field.
    [*] Every element of an array, as in @.Payload.registerKey[*].name.
    == Equality, as in @.ext=='txt'.
    >= Numeric comparison, as in @.sizeInBytes>=1048576.
    in [ ... ] Membership of a set, as in @.Payload.status in ['failed','timeout'].
    && and || AND and OR within a single expression.

    For the full JsonPath syntax, see the JsonPath project.

    Troubleshooting

    If a filter is not behaving as you expect, the cause is almost always the expression or the assumed payload shape rather than the webhook.

    • No callbacks arrive at all. Check that the field you filter on exists in that event’s payload, spelled exactly as the event defines it, including case. @.Payload.status and @.payload.status are not the same path.
    • The path is wrong by one level. $ is the payload object, so do not include payload in the path. Filtering on @.hook.event or another envelope field is not filtering on the payload.
    • The value or type does not match. A string comparison against a number, or a value that differs in case, does not match. '36' and 36 are not the same value.
    • The payload is not the shape you assumed. Fields are defined per event and are not shared across Autodesk services. Confirm against the reference page for the exact event you subscribed to.
    • Every callback still arrives. Confirm the filter was actually stored on the webhook by retrieving the webhook and checking the field. See Retrieve a List of Webhooks.

    Test the expression against a sample of the event’s real payload before concluding the filter is at fault.

    What Filtering Cannot Do

    • It cannot filter on data that is not in the payload. If the value you need is not in the event payload, a filter cannot reach it. Where you need extra context in the callback, hookAttribute lets you store your own data on the webhook. See the Field Guide.
    • It cannot widen a subscription. A filter only removes callbacks. It never adds events that the system, event, and scope of the webhook do not already match.
    • It does not change delivery behaviour. Callbacks that are sent are still subject to the response requirements, retries, and inactivation rules in Event Delivery Guarantees.

    Fields per Event

    Which fields you can filter on depends entirely on the event you subscribe to. There is no common set of payload fields across Autodesk services, and a field that exists for one event may be absent or differently named for another.

    Always take the field names from the reference page for the event you subscribed to, under Supported Events, and from the tutorial for that Autodesk service in the How-to Guide.