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. 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. .. 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, } ] } 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: .. code-block:: json { "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: .. 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" } } ] } .. 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.