Hooks
Hooks are used to automate processes in the API. A hook listens to certain triggers and executes its associated action.
Attributes
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 |
Specification of what resource (and action) the hook listens to and additional optional predicates. |
✓ |
|
action |
Specification of what should be performed when the hook gets executed. |
✓ |
Relationship |
Type |
Description |
Required |
|---|---|---|---|
owner |
organization or shop |
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.
Warning
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.
Tip
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.
Warning
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.
The order in which hooks are executed
Endpoints
GET /hooks
Retrieving a list of hooks.
Scope
Any of the following scopes:
organizations.manage
Request
GET /hooks HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/hooks
Example response
{
"data": [
{
"type": "hooks",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9",
"attributes": {
"name": "DPD Next Day for medium packages",
"order": 300,
"active": true,
"trigger": {
"resource_type": "shipments",
"resource_action": "create",
"predicates": [
{
"pointer": "/attributes/physical_properties/weight",
"operator": "==",
"value": 1000
}
]
},
"action": {
"action_type": "update-resource",
"values": [
{
"pointer": "/relationships/service/data/id",
"value": "8321796d-5205-4e13-963f-61bf7db34390"
},
{
"pointer": "/relationships/service/data/type",
"value": "services"
}
]
}
},
"relationships": {
"owner": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/hooks/5c868557-0827-4d21-a7f4-9820f01769f4"
}
}
],
"meta": {
"total_pages": 1,
"total_records": 1
},
"links": {
"self": "https://api.sandbox.myparcel.com/hooks?page[number]=1&page[size]=30",
"first": "https://api.sandbox.myparcel.com/hooks?page[number]=1&page[size]=30",
"last": "https://api.sandbox.myparcel.com/hooks?page[number]=1&page[size]=30"
}
}
GET /hooks/{hook_id}
Retrieving a specific hook.
Scope
Any of the following scopes:
organizations.manage
Request
GET /hooks/{hook_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/hooks/be7f6752-34e0-49a1-a832-bcc209450ea9
Example response
{
"data": {
"type": "hooks",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9",
"attributes": {
"name": "DPD Next Day for medium packages",
"order": 300,
"active": true,
"trigger": {
"resource_type": "shipments",
"resource_action": "create",
"predicates": [
{
"pointer": "/attributes/physical_properties/weight",
"operator": "==",
"value": 1000
}
]
},
"action": {
"action_type": "update-resource",
"values": [
{
"pointer": "/relationships/service/data/id",
"value": "8321796d-5205-4e13-963f-61bf7db34390"
},
{
"pointer": "/relationships/service/data/type",
"value": "services"
}
]
}
},
"relationships": {
"owner": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/hooks/5c868557-0827-4d21-a7f4-9820f01769f4"
}
}
}
POST /hooks
Create a hook.
Scope
Any of the following scopes:
organizations.manage
Request
POST /hooks HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/hooks
{
"data": {
"type": "hooks",
"attributes": {
"name": "DPD Next Day for medium packages",
"order": 300,
"active": true,
"trigger": {
"resource_type": "shipments",
"resource_action": "create",
"predicates": [
{
"pointer": "/attributes/physical_properties/weight",
"operator": "==",
"value": 1000
}
]
},
"action": {
"action_type": "update-resource",
"values": [
{
"pointer": "/relationships/service/data/id",
"value": "8321796d-5205-4e13-963f-61bf7db34390"
},
{
"pointer": "/relationships/service/data/type",
"value": "services"
}
]
}
},
"relationships": {
"owner": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
}
}
}
Example response
{
"data": {
"type": "hooks",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9",
"attributes": {
"name": "DPD Next Day for medium packages",
"order": 300,
"active": true,
"trigger": {
"resource_type": "shipments",
"resource_action": "create",
"predicates": [
{
"pointer": "/attributes/physical_properties/weight",
"operator": "==",
"value": 1000
}
]
},
"action": {
"action_type": "update-resource",
"values": [
{
"pointer": "/relationships/service/data/id",
"value": "8321796d-5205-4e13-963f-61bf7db34390"
},
{
"pointer": "/relationships/service/data/type",
"value": "services"
}
]
}
},
"relationships": {
"owner": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/hooks/5c868557-0827-4d21-a7f4-9820f01769f4"
}
}
}
PATCH /hooks/{hook_id}
Update a hook.
Scope
Any of the following scopes:
organizations.manage
Request
In this request the priority of this hook is adjusted.
POST /hooks/{hook_id} HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/hooks/be7f6752-34e0-49a1-a832-bcc209450ea9
{
"data": {
"type": "hooks",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9",
"attributes": {
"order": 100
}
}
}
Example response
{
"data": {
"type": "hooks",
"id": "be7f6752-34e0-49a1-a832-bcc209450ea9",
"attributes": {
"name": "DPD Next Day for medium packages",
"order": 100,
"active": true,
"trigger": {
"resource_type": "shipments",
"resource_action": "create",
"predicates": [
{
"pointer": "/attributes/physical_properties/weight",
"operator": "==",
"value": 1000
}
]
},
"action": {
"action_type": "update-resource",
"values": [
{
"pointer": "/relationships/service/data/id",
"value": "8321796d-5205-4e13-963f-61bf7db34390"
},
{
"pointer": "/relationships/service/data/type",
"value": "services"
}
]
}
},
"relationships": {
"owner": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/hooks/5c868557-0827-4d21-a7f4-9820f01769f4"
}
}
}