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 :ref:`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 :doc:`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 .. _hook-trigger-predicate: 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 :doc:`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 :ref:`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: .. code-block:: json { "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: .. code-block:: json { "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 _____________________ 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. .. code-block:: json { "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). .. code-block:: json { "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. .. code-block:: json { "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. .. code-block:: json { "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. .. code-block:: json { "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. .. code-block:: json { "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. .. code-block:: json { "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. .. code-block:: json { "resource_type": "shipments", "resource_action": "create", "predicates": [ { "operator": ">=", "pointer": "/attributes/items/{anyOf}/quantity", "value": 2, } ] }