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`.	✓
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 or integer	The value to compare the resource property indicated by the `pointer` attribute to.	✓

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