Skip to content

Commit f503f95

Browse files
keharperkeharper
authored
Merge pull request AdobeDocs#391 from AdobeDocs/migrate-services-topics
Move webhook REST endpoints from services repo
2 parents 38d9845 + 9534326 commit f503f95

File tree

2 files changed

+145
-50
lines changed

2 files changed

+145
-50
lines changed

‎src/pages/webhooks/api.md

Lines changed: 144 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -16,44 +16,44 @@ The `GET /rest/all/V1/webhooks/list` endpoint returns a list of all subscribed w
1616

1717
```json
1818
[
19-
{
20-
"webhook_method": "observer.sales_order_place_before",
21-
"webhook_type": "after",
22-
"batch_name": "sales_order",
23-
"batch_order": 100,
24-
"hook_name": "sales_order_status",
25-
"url": "/hook-url",
26-
"priority": 100,
27-
"required": true,
28-
"soft_timeout": 1000,
29-
"timeout": 2000,
30-
"method": "",
31-
"fallback_error_message": "Unable to validate product",
32-
"ttl": 6000,
33-
"fields": [
34-
{
35-
"name": "name",
36-
"source": "data.product.name"
37-
},
38-
{
39-
"name": "price",
40-
"source": "data.product.price"
41-
}
42-
],
43-
"rules": [
44-
{
45-
"field": "data.product.sku",
46-
"operator": "regex",
47-
"value": "\/.*car.*\/"
48-
}
49-
],
50-
"headers": [
51-
{
52-
"name": "header-name",
53-
"value": "header-value"
54-
}
55-
]
56-
}
19+
{
20+
"webhook_method": "observer.sales_order_place_before",
21+
"webhook_type": "after",
22+
"batch_name": "sales_order",
23+
"batch_order": 100,
24+
"hook_name": "sales_order_status",
25+
"url": "/hook-url",
26+
"priority": 100,
27+
"required": true,
28+
"soft_timeout": 1000,
29+
"timeout": 2000,
30+
"method": "",
31+
"fallback_error_message": "Unable to validate product",
32+
"ttl": 6000,
33+
"fields": [
34+
{
35+
"name": "name",
36+
"source": "data.product.name"
37+
},
38+
{
39+
"name": "price",
40+
"source": "data.product.price"
41+
}
42+
],
43+
"rules": [
44+
{
45+
"field": "data.product.sku",
46+
"operator": "regex",
47+
"value": "\/.*car.*\/"
48+
}
49+
],
50+
"headers": [
51+
{
52+
"name": "header-name",
53+
"value": "header-value"
54+
}
55+
]
56+
}
5757
]
5858
```
5959

@@ -69,23 +69,23 @@ curl --request GET \
6969
--header 'Authorization: Bearer <TOKEN>'
7070
```
7171

72-
### Get supported webhooks for SaaS
72+
## Get supported webhooks for SaaS
7373

7474
<Edition name="saas" />
7575

7676
The `GET /V1/webhooks/supportedList` endpoint returns the events supported in Adobe Commerce as a Cloud Service (SaaS). The response body is similar to the following:
7777

7878
```json
7979
[
80-
{
81-
"name": "observer.sales_quote_add_item"
82-
},
83-
{
84-
"name": "observer.checkout_cart_product_add_before"
85-
},
86-
{
87-
"name": "observer.catalog_product_save_after"
88-
},
80+
{
81+
"name": "observer.sales_quote_add_item"
82+
},
83+
{
84+
"name": "observer.checkout_cart_product_add_before"
85+
},
86+
{
87+
"name": "observer.catalog_product_save_after"
88+
},
8989
...
9090
]
9191
```
@@ -94,10 +94,105 @@ The access token used in the request must have access to the `Webhooks > Webhook
9494

9595
**Example usage:**
9696

97-
The following cURL command returns a list of all suported webhooks in SaaS.
97+
The following cURL command returns a list of all supported webhooks in SaaS.
9898

9999
```bash
100100
curl --request GET \
101101
--url <ADOBE_COMMERCE_SAAS_REST_ENDPOINT>/V1/webhooks/supportedList \
102102
--header 'Authorization: Bearer <TOKEN>'
103103
```
104+
105+
## Subscribe a webhook
106+
107+
<Edition name="saas" />
108+
109+
To subscribe a webhook, make a `POST` request to the `/V1/webhooks/subscribe` endpoint. [Create a webhook](./conditional-webhooks.md) provides details about the contents of a webhook.
110+
111+
The following restrictions apply to the webhook request:
112+
113+
- Any specified `fields` must have a `name`.
114+
- `name` cannot be a null.
115+
- Any `rules` must have a `field`, `value`, and `operator`.
116+
- `field` and `operator` cannot be null.
117+
- The `operator` must be one of the supported options listed under [conditional webhooks](./conditional-webhooks.md).
118+
- Any `headers` must have a `name` and `value`.
119+
- `name` and `value` cannot be null.
120+
- `timeout`, `ttl`, and `soft_timeout` must be non-negative integers.
121+
122+
The request body must include the following attributes:
123+
124+
| Attribute | Type | Description | Is required | Default |
125+
|---|---|---|---|---|
126+
| `hook_name` | String | A hook name that is unique within a batch. This value must contain English alphanumeric characters and underscores (_) only.| true | Not applicable |
127+
| `url` | String | The HTTP endpoint to send the request for processing. | true | Not applicable |
128+
| `webhook_method` | String | The webhook code name. The value must be in the form `<type>.<webhook_name>`, where `type` is either `observer` or `plugin`, and `webhook_name` matches a valid Commerce webhook name. | true | Not applicable |
129+
| `webhook_type` | String | Specifies whether to execute the webhook `before` or `after` the original action. | true | Not applicable |
130+
| `batch_name` | String | A unique name for the batch. This value must contain English alphanumeric characters and underscores (_) only.| true | Not applicable |
131+
132+
### Request body
133+
134+
```json
135+
{
136+
"webhook": {
137+
"webhook_method": "observer.checkout_cart_product_add_before",
138+
"webhook_type": "after",
139+
"batch_name": "add_product",
140+
"batch_order": 100,
141+
"hook_name": "validate_product",
142+
"url": "https://<host>.com/validate-product-add",
143+
"priority": 100,
144+
"required": true,
145+
"timeout": 2000,
146+
"ttl": 6000,
147+
"soft_timeout": 1000,
148+
"fallback_error_message": "Unable to validate product",
149+
"fields": [
150+
{
151+
"name": "name",
152+
"source": "data.product.name"
153+
},
154+
{
155+
"name": "price",
156+
"source": "data.product.price"
157+
}
158+
],
159+
"rules": [
160+
{
161+
"field": "data.product.sku",
162+
"operator": "regex",
163+
"value": "/.*car.*/"
164+
}
165+
],
166+
"headers": [
167+
{
168+
"name": "CLIENT_ID",
169+
"value": "abcasdf-12abcd3-45efabc4"
170+
}
171+
]
172+
}
173+
}
174+
```
175+
176+
## Unsubscribe a webhook
177+
178+
<Edition name="saas" />
179+
180+
The unsubscribe endpoint allows you to delete an existing webhook subscription. To delete a webhook, make a `POST` request to the `/V1/webhooks/unsubscribe` endpoint. The request body must include the following attributes from the existing webhook:
181+
182+
- `webhook_method`
183+
- `webhook_type`
184+
- `batch_name`
185+
- `hook_name`
186+
187+
### Request body
188+
189+
```json
190+
{
191+
  "webhook": {
192+
    "webhook_method": "observer.checkout_cart_product_add_before",
193+
    "webhook_type": "after",
194+
    "batch_name": "add_product",
195+
    "hook_name": "validate_product"
196+
  }
197+
}
198+
```

‎src/pages/webhooks/create-webhooks.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ With this knowledge, you can create a webhook, which defines the following sets
2727

2828
* Optional rules that trigger only when certain conditions are met, such as when a string matches a specific value.
2929

30-
In Adobe Commerce as a Cloud Service, you can create a webhook subscription in the Admin or by using a REST endpoint. (See [Webhooks in Adobe Commerce as a Cloud Service](https://developer.adobe.com/commerce/services/cloud/guides/rest/webhooks/) for details on using REST.) In Platform as a Service (PaaS) and on-premises environments, you must create an `app/etc/webhooks.xml` file or create a custom module that includes a `<custom-module-root>/etc/webhooks.xml` file.
30+
In Adobe Commerce as a Cloud Service, you can create a webhook subscription in the Admin or by using a REST endpoint. (See [Subscribe a webhook](./api.md#subscribe-a-webhook) for details on using REST.) In Platform as a Service (PaaS) and on-premises environments, you must create an `app/etc/webhooks.xml` file or create a custom module that includes a `<custom-module-root>/etc/webhooks.xml` file.
3131

3232
## Define webhook properties
3333

0 commit comments

Comments
 (0)