Hooks

Hooks are used to automate processes in the API.
A hook listens to certain triggers and executes its associated action.

Attributes

API specification

Attribute Type Description Required
name string A name for users to recognize the hook by.
order integer Position of the hook in the queue of hooks when multiple hooks apply (lower order indicates it will be executed earlier).
active boolean Whether or not the hook should executed.
trigger hook trigger Specification of what resource (and action) the hook listens to and additional optional predicates.
action hook action Specification of what should be performed when the hook gets executed.
Relationship Type Description Required
owner organizations
OR
shops
The owner (generally the creator) of the hook. The owner influences when a hook is triggered and its priority.

Hook ordering

Multiple hooks can be triggered by the same resource action. This means that the hooks will take turns executing. The order of the hooks is determined by two things: the owner of the hook and the order attribute of the hook.

A hook will not overwrite any values. If multiple hooks set the same resource property using the update-resource action, the first hook to execute will set the value. All subsequent hooks will not overwrite the same property.

The owner of the hook

Hooks follow hierarchy in the API. This means that if the owner of a hook is of type organizations, all (child) shops that relate to that organization will automatically have the hook applied as well. As mentioned before, the order in which the hooks are executed is influenced by the owner of the hook, prioritizing lower ranked owners first. This means that first all hooks created by a shop will be executed and then all hooks created by the shop’s parent organization will execute.

The order attribute

The order in which hooks with the same owner are executed is influenced by the order attribute of the hook. Hooks with a lower order are executed earlier.

To avoid having to adjust the order of all other hooks when creating a new hook that should be executed before existing ones, the value of the order attribute should be multiplications of 100. This makes it easier to “insert” a new hook between/before existing ones.

If two hooks have the same owner and the same value for order, they will be executed in effectively random order!

The diagram below shows the order in which hooks are executed in a more visual manner.

Hooks ordering

The order in which hooks are executed

Endpoints

GET /hooks
GET /hooks/{hook_id}
POST /hooks
PATCH /hooks/{hook_id}
12-03-2019