Skip to content

Commit 00ac1b0

Browse files
oshmyheliukoshmyheliuk
committed
CEXT-2484: Document new operations
1 parent 4bb3fde commit 00ac1b0

File tree

2 files changed

+401
-11
lines changed

2 files changed

+401
-11
lines changed

‎src/pages/webhooks/responses.md

Lines changed: 154 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,28 @@ keywords:
77

88
# Webhook responses and logging
99

10-
Currently, Adobe Commerce webhooks only support two responses: `success` and `exception`. Responses that require additional processing, such as parsing the results of a GET response, are not supported.
10+
Currently, Adobe Commerce webhooks only support responses in JSON format. The response may be a single operation or the array of operations which will be executed consequently.
11+
Each operation must contain some required fields based on the desired operation.
1112

1213
Exceptions and notices are logged in the `<installation_directory>/var/log/system.log` file.
1314

1415
## Responses
1516

16-
The endpoint is expected to return a `200` response and a JSON object that indicates the result of the operation. The object can contain the following fields:
17+
The endpoint is expected to return a `200` response and a JSON object or array of objects that indicates the result of the operation. The object can contain the list of fields based on the operation (`op`) which should be performed.
1718

18-
Field | Description
19+
At the moment Adobe Commerce webhooks support 5 different operations:
20+
21+
operation | Description
1922
--- | ---
20-
`op` | The status of the operation: either `success` or `exception`.
21-
`class` | If the `op` status is `exception`, optionally specifies the exception class. If `class` is not set, the `\Magento\Framework\Exception\LocalizedException` will be thrown.
22-
`message` | If the `op` status is `exception`, optionally specifies the exception message. If this field is not explicitly set, then the message defined in the `fallbackErrorMessage` configuration field will be returned. If `fallbackErrorMessage` is not set, the system default error message will be shown.
23+
`success` | the process that triggered the original event continues without any changes.
24+
`exception` | causes Commerce to terminate the process that triggered the original event
25+
`add` | updates the arguments in the original events by adding data described in the operation
26+
`replace` | replaces the arguments values in the original events based based on the response
27+
`remove` | removes values or nodes from the arguments in the original event by provided path
28+
29+
### Success operation
30+
31+
The `success` operation is returned in cases when changes are not needed and the process that triggered the original event continues without any changes.
2332

2433
The response of a successful request is as follows:
2534

@@ -29,7 +38,15 @@ The response of a successful request is as follows:
2938
}
3039
```
3140

32-
The process that triggered the original event continues without any changes.
41+
### Exception operation
42+
43+
The `exception` operation causes Commerce to terminate the process that triggered the original event. The exception is logged in `<installation_directory>/var/log/system.log`.
44+
45+
Field | Type | Description
46+
--- | --- | ---
47+
`op` | required | `exception`
48+
`class` | optional | specifies the exception class. If `class` is not set, the `\Magento\Framework\Exception\LocalizedException` will be thrown.
49+
`message` | optional | specifies the exception message. If this field is not explicitly set, then the message defined in the `fallbackErrorMessage` configuration field will be returned. If `fallbackErrorMessage` is not set, the system default error message will be shown.
3350

3451
If an error occurs, the response is similar to the following:
3552

@@ -41,7 +58,136 @@ If an error occurs, the response is similar to the following:
4158
}
4259
```
4360

44-
The `exception` operation causes Commerce to terminate the process that triggered the original event. The exception is logged in `<installation_directory>/var/log/system.log`.
61+
### Add operation
62+
63+
The `add` operation causes Commerce to add provided `value` to the provided `path` to the triggered event arguments
64+
65+
Field | Type | Description
66+
--- |----------| ---
67+
`op` | required | `add`
68+
`path` | required | specifies the path at which the `value` should be added to the triggered event arguments
69+
`value` | required | specifies the value that should be added, can be as a single value or in the array format
70+
`instance` | optional | specifies the DataObject class name which should be created based on `value` and added to the provided `path`. Used for the cases when the object should be added in provided path.
71+
72+
For example, we want to add a new shipping method to the triggered event result payload:
73+
The result is an array of `Magento\Quote\Model\Cart\ShippingMethod` objects:
74+
75+
```php
76+
$result = [
77+
0 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
78+
1 => {Magento\Quote\Model\Cart\ShippingMethodInterface}
79+
];
80+
```
81+
82+
To add a new shipping method to that result, the response from the webhook would look like:
83+
84+
```json
85+
{
86+
"op": "add",
87+
"path": "result",
88+
"value": {
89+
"data": {
90+
"amount": "5",
91+
"base_amount": "5",
92+
"carrier_code": "newshipmethod",
93+
"carrier_title": "Webhook new shipping method",
94+
}
95+
},
96+
"instance": "Magento\\Quote\\Api\\Data\\ShippingMethodInterface"
97+
}
98+
```
99+
100+
Based on this operation the new instance of `Magento\Quote\Model\Cart\ShippingMethodInterface` will be created and added to the result array of shipping methods.
101+
102+
```php
103+
$result = [
104+
0 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
105+
1 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
106+
2 => {Magento\Quote\Model\Cart\ShippingMethodInterface}
107+
];
108+
```
109+
110+
### Replace operation
111+
112+
The `replaces` operation causes Commerce to replace a value in triggered event arguments for the provided `path`
113+
114+
Field | Type | Description
115+
--- |----------| ---
116+
`op` | required | `replace`
117+
`path` | required | specifies the path at which the value should be replaced with the provided `value`
118+
`value` | required | specifies the new value that replaces the value by provided `path`, can be as a single or in the array format
119+
`instance` | optional | specifies the DataObject class name which should be created based on `value` and used as value to replaced by path `path`.
120+
121+
For example, we want to a replace a nested element in the triggered event result payload:
122+
123+
```php
124+
$result = [
125+
'shipping_methods' => [
126+
'shipping_method_one' => [
127+
'amount' => 5
128+
]
129+
]
130+
];
131+
```
132+
133+
The response from the webhook endpoint:
134+
135+
```json
136+
{
137+
"op": "replace",
138+
"path": "result/shipping_methods/shipping_method_one/amount",
139+
"value": 6
140+
}
141+
```
142+
143+
The updated result will be modified to:
144+
145+
```php
146+
$result = [
147+
'shipping_methods' => [
148+
'shipping_method_one' => [
149+
'amount' => 6
150+
]
151+
]
152+
];
153+
```
154+
155+
### Remove operation
156+
157+
The `remove` operation causes Commerce to remove a value or node in triggered event arguments by the provided `path`
158+
159+
Field | Type | Description
160+
--- |----------| ---
161+
`op` | required | `remove`
162+
`path` | required | specifies the path at which the value should be removed
163+
164+
For example, we want to a remove en element `key2` from the triggered event result payload:
165+
166+
```php
167+
$result = [
168+
'key1' => 'value1',
169+
'key2' => 'value2',
170+
'key3' => 'value3',
171+
];
172+
```
173+
174+
The response from the webhook endpoint:
175+
176+
```json
177+
{
178+
"op": "remove",
179+
"path": "result/key2"
180+
}
181+
```
182+
183+
The updated result will be modified to:
184+
185+
```php
186+
$result = [
187+
'key1' => 'value1',
188+
'key3' => 'value3',
189+
];
190+
```
45191

46192
## Logging
47193

0 commit comments

Comments
 (0)