Hook trigger

A hook trigger contains the criteria for when a hook should trigger. It determines what resource and action should trigger the hook.

Attributes

Attribute	Type	Description	Required
resource_type	string	The type of resource that causes the hook to trigger.	✓
resource_action	string enum: `create` `update` `import`	The resource action that should trigger the hook.	✓
predicates	array of predicate objects	Used to more specifically trigger hooks based on the target resource.

Note

At this time, the only supported combinations of resource_action and resource_type are:

create + shipments = used to modify shipment attributes or relationships when creating shipments
create + shipment-statuses = used to trigger webhooks to inform external systems of new shipment-statuses
update + shipment-statuses = used next to create if you want to receive (redundant) carrier-statuses added to the same shipment-status
import + shipments = used to modify shipment attributes when importing them from an integration

Predicate

A predicate is a statement that contains variables and resolves to be either true or false depending on the values of these variables. To resolve a predicate, an operator, a pointer and a value are required. If all predicates resolve to true the hook action will be executed.

Attribute	Type	Description	Required
pointer	string	JSON pointer formatted string pointing to the resource property that should be compared with the `value` attribute using the `operator`. Additionally, when targeting properties of objects in an array, the `{anyOf}` keyword can be used to target any of the items in an array.	✓
operator	string enum: `==` `!=` `>` `<` `>=` `<=` `contains` `in`	Comparison operator used to compare two values. See the section on the contains operator for more information on how it works.	✓
value	string, float, array, object or integer	The value to compare the resource property indicated by the `pointer` attribute to.	✓

Using objects as predicate values

When a resource property contains a complex object structure, you can use an object as the predicate value to match against the object. This is particularly useful for comparing nested structures like prices, dimensions, or addresses.

The following example shows a trigger that activates when a shipment is created with a specific total value:

{
  "resource_type": "shipments",
  "resource_action": "create",
  "predicates": [
    {
      "operator": "==",
      "pointer": "/attributes/total_value",
      "value": {
        "amount": 500,
        "currency": "EUR"
      }
    }
  ]
}

You can also use object values to match specific address components. This trigger will activate when a shipment is created to a specific recipient address:

{
  "resource_type": "shipments",
  "resource_action": "create",
  "predicates": [
    {
      "operator": "==",
      "pointer": "/attributes/recipient_address",
      "value": {
        "street_1": "Baker Street",
        "street_number": 221,
        "street_number_suffix": "B",
        "city": "London",
        "postal_code": "NW1 6XE",
        "country_code": "GB"
      }
    }
  ]
}

The contains operator

The contains operator functions differently depending on the type of the resource property it is targeting:

String properties

When both the resource property and the comparison value are strings, the operator performs a case-insensitive substring search. The predicate evaluates to true if the resource property contains the comparison value as a substring.

{
  "operator": "contains",
  "pointer": "/attributes/description",
  "value": "fragile"
}

This will match shipments with descriptions like “Fragile items”, “FRAGILE - Handle with care”, or “Non-fragile”.

Array properties with string values

When the resource property is an array and the comparison value is a string, the operator checks if the array contains that string value. The comparison is case-insensitive and looks for an exact match (not a substring).

{
  "operator": "contains",
  "pointer": "/attributes/tags",
  "value": "express"
}

This will match if the tags array contains the string “express” (case-insensitive), such as ["Express", "Priority"] or ["standard", "EXPRESS"].

Array properties with non-string values

When the resource property is an array and the comparison value is a non-string primitive (number, boolean, etc.), the operator performs a strict equality check.

{
  "operator": "contains",
  "pointer": "/attributes/item_ids",
  "value": 12345
}

This will match only if the item_ids array contains the exact number 12345.

Object properties with object values

When both the resource property and the comparison value are objects, the operator checks if all key-value pairs in the comparison value are present in the resource property. The resource property may contain additional keys not specified in the comparison value.

{
  "operator": "contains",
  "pointer": "/attributes/recipient_address",
  "value": {
    "country_code": "NL",
    "postal_code": "1234 AB"
  }
}

This will match if the recipient_address object contains at least the keys country_code with value "NL" and postal_code with value "1234 AB", regardless of any other keys present.

Note

If the comparison value is null, the contains operator will always return false.

More examples

The trigger below will cause a hook to activate whenever any shipment is updated with a new status.

{
  "resource_type": "shipment-statuses",
  "resource_action": "update"
}

The following trigger contains predicates and will cause its associated hook to trigger only when a shipment is created with a weight below 5 kg.

{
  "resource_type": "shipments",
  "resource_action": "create",
  "predicates": [
    {
      "operator": "<",
      "pointer": "attributes/physical_properties/weight",
      "value": 5000
    }
  ]
}

A trigger can have as many predicates as the user might find necessary. The below trigger will cause a hook to trigger when a shipment is created that weighs less than 5 kg and is sent to anywhere in Spain or Portugal but not to Madrid.

{
  "resource_type": "shipments",
  "resource_action": "create",
  "predicates": [
    {
      "operator": "<",
      "pointer": "attributes/physical_properties/weight",
      "value": 5000
    },
    {
      "operator": "!=",
      "pointer": "attributes/recipient_address/city",
      "value": "Madrid"
    },
    {
      "operator": "in",
      "pointer": "attributes/recipient_address/country_code",
      "value": ["ES", "PT"]
    }
  ]
}

Predicates can target properties of objects in an array by using the {anyOf} keyword in the pointer. The trigger below will cause a hook to trigger when a shipment is created that contains at least one item with a quantity of at least 2.

{
  "resource_type": "shipments",
  "resource_action": "create",
  "predicates": [
    {
      "operator": ">=",
      "pointer": "/attributes/items/{anyOf}/quantity",
      "value": 2,
    }
  ]
}