Skip to content

Commit 6f1340b

Browse files
keharperkeharper
authored
Merge pull request AdobeDocs#102 from oshmyheliuk/CEXT-2484
CEXT-2484: Document new operations
2 parents 4bb3fde + bf9b600 commit 6f1340b

File tree

2 files changed

+402
-12
lines changed

2 files changed

+402
-12
lines changed

‎src/pages/webhooks/responses.md

Lines changed: 155 additions & 9 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 support responses in JSON format only. The response may be a single operation or an array of operations to be executed afterward.
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. Each operation object can contain the list of fields based on the operation (`op`) which should be performed.
1718

18-
Field | Description
19+
Adobe Commerce webhooks support the following 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 event by adding data described in the operation
26+
`replace` | Replaces argument values in the original event, based on the response.
27+
`remove` | Removes values or nodes from the arguments in the original event by the provided path
28+
29+
### Success operation
30+
31+
The `success` operation is returned when changes are not needed. The process that triggered the original event continues without any changes.
2332

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

@@ -29,19 +38,156 @@ 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 | Contains `exception`.
48+
`class` | Optional | Specifies the exception class. If `class` is not set, `\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 returned.
3350

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

3653
```json
3754
{
3855
"op": "exception",
3956
"class": "Path\\To\\Exception\\Class",
40-
"message": "The product can not be added to the cart as it is out of the stock"
57+
"message": "The product cannot be added to the cart because it is out of the stock"
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 the provided `value` to the provided `path` to the triggered event arguments
64+
65+
Field | Type | Description
66+
--- |----------| ---
67+
`op` | Required | Contains `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 to be added. This can be as a single value or in an array format.
70+
`instance` | Optional | Specifies the `DataObject` class name to create, based on the `value` and added to the provided `path`. Use this field for 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 `replace` operation causes Commerce to replace a value in triggered event arguments for the provided `path`
113+
114+
Field | Type | Description
115+
--- |----------| ---
116+
`op` | Required | Contains `replace`.
117+
`path` | Required | Specifies the path at which the value should be replaced with the provided `value`.
118+
`value` | Required | Specifies the replacement value. This can be as a single value or in an array format.
119+
`instance` | Optional | Specifies the `DataObject` class name to create, based on the `value` and added to the provided `path`.
120+
121+
The following example replaces 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 | Contains `remove`.
162+
`path` | Required | Specifies the path at which the value should be removed.
163+
164+
The following example removes 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)