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. The `contains` operator checks if a string contains a substring or if an array property contains a string. The `in` operator is used to check if a property value is in the target array.	✓
value	string, float, array, object or integer	The value to compare the resource property indicated by the `pointer` attribute to. Note that `object` type values can only be used with the `==` and `!=` operators.	✓

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,
    }
  ]
}

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 entire object. This is particularly useful for comparing nested structures like prices, dimensions, or addresses.

Warning

Object values can only be used with the == (equals) and != (not equals) operators. The comparison performs a deep equality check, meaning all properties in the object must match exactly.

The following example shows a trigger that activates when a shipment is created with specific physical dimensions:

{
  "resource_type": "shipments",
  "resource_action": "create",
  "predicates": [
    {
      "operator": "==",
      "pointer": "/attributes/physical_properties",
      "value": {
        "height": 10,
        "width": 20,
        "length": 30
      }
    }
  ]
}

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"
      }
    }
  ]
}

Tip

When using object values in predicates, all properties in the value object must be present and match exactly in the resource for the predicate to evaluate to true. If you only need to match a single property within an object, use a more specific pointer path to target that property directly instead of comparing the entire object.