REST endpoints for webhooks

Adobe Commerce provides several REST endpoints that interact with the webhooks processes. These endpoints require an admin token.

Get a list of all subscribed webhooks

The GET /rest/all/V1/webhooks/list endpoint returns a list of all subscribed webhooks. The response body is similar to the following:

[
    {
        "webhook_method": "observer.sales_order_place_before",
        "webhook_type": "after",
        "batch_name": "sales_order",
        "batch_order": 100,
        "hook_name": "sales_order_status",
        "url": "/hook-url",
        "priority": 100,
        "required": true,
        "soft_timeout": 1000,
        "timeout": 2000,
        "method": "",
        "fallback_error_message": "Unable to validate product",
        "ttl": 6000,
        "fields": [
            {
                "name": "name",
                "source": "data.product.name"
            },
            {
                "name": "price",
                "source": "data.product.price"
            }
        ],
        "rules": [
            {
                "field": "data.product.sku",
                "operator": "regex",
                "value": "\/.*car.*\/"
            }
        ],
        "headers": [
            {
                "name": "header-name",
                "value": "header-value"
            }
        ]
    }
]
Copied to your clipboard
[
    {
        "webhook_method": "observer.sales_order_place_before",
        "webhook_type": "after",
        "batch_name": "sales_order",
        "batch_order": 100,
        "hook_name": "sales_order_status",
        "url": "/hook-url",
        "priority": 100,
        "required": true,
        "soft_timeout": 1000,
        "timeout": 2000,
        "method": "",
        "fallback_error_message": "Unable to validate product",
        "ttl": 6000,
        "fields": [
            {
                "name": "name",
                "source": "data.product.name"
            },
            {
                "name": "price",
                "source": "data.product.price"
            }
        ],
        "rules": [
            {
                "field": "data.product.sku",
                "operator": "regex",
                "value": "\/.*car.*\/"
            }
        ],
        "headers": [
            {
                "name": "header-name",
                "value": "header-value"
            }
        ]
    }
]

The administrator must be granted access to the Magento_AdobeCommerceWebhooks::webhooks_list resource.

Example usage:

The following cURL command returns returns a list of all subscribed webhooks.

curl --request GET \
   --url <ADOBE_COMMERCE_URL>/rest/all/V1/webhooks/list \
   --header 'Authorization: Bearer <TOKEN>'
Copied to your clipboard
curl --request GET \
   --url <ADOBE_COMMERCE_URL>/rest/all/V1/webhooks/list \
   --header 'Authorization: Bearer <TOKEN>'

Get supported webhooks for SaaS

SaaS only

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:

[
    {
        "name": "observer.sales_quote_add_item"
    },
    {
        "name": "observer.checkout_cart_product_add_before"
    },
    {
        "name": "observer.catalog_product_save_after"
    },
  ...
]
Copied to your clipboard
[
    {
        "name": "observer.sales_quote_add_item"
    },
    {
        "name": "observer.checkout_cart_product_add_before"
    },
    {
        "name": "observer.catalog_product_save_after"
    },
  ...
]

The access token used in the request must have access to the Webhooks > Webhooks Management > Webhooks List resource. See REST authentication for information on authentication for SaaS.

Example usage:

The following cURL command returns a list of all supported webhooks in SaaS.

curl --request GET \
   --url <ADOBE_COMMERCE_SAAS_REST_ENDPOINT>/V1/webhooks/supportedList \
   --header 'Authorization: Bearer <TOKEN>'
Copied to your clipboard
curl --request GET \
   --url <ADOBE_COMMERCE_SAAS_REST_ENDPOINT>/V1/webhooks/supportedList \
   --header 'Authorization: Bearer <TOKEN>'

SaaS only

To subscribe a webhook, make a POST request to the /V1/webhooks/subscribe endpoint. Create a webhook provides details about the contents of a webhook.

The following restrictions apply to the webhook request:

Any specified fields must have a name.
- name cannot be a null.
Any rules must have a field, value, and operator.
- field and operator cannot be null.
- The operator must be one of the supported options listed under conditional webhooks.
Any headers must have a name and value.
- name and value cannot be null.
timeout, ttl, and soft_timeout must be non-negative integers.

The request body must include the following attributes:

Attribute	Type	Description	Is required	Default
`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
`url`	String	The HTTP endpoint to send the request for processing.	true	Not applicable
`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
`webhook_type`	String	Specifies whether to execute the webhook `before` or `after` the original action.	true	Not applicable
`batch_name`	String	A unique name for the batch. This value must contain English alphanumeric characters and underscores (_) only.	true	Not applicable

Request body

{
  "webhook": {
    "webhook_method": "observer.checkout_cart_product_add_before",
    "webhook_type": "after",
    "batch_name": "add_product",
    "batch_order": 100,
    "hook_name": "validate_product",
    "url": "https://<host>.com/validate-product-add",
    "priority": 100,
    "required": true,
    "timeout": 2000,
    "ttl": 6000,
    "soft_timeout": 1000,
    "fallback_error_message": "Unable to validate product",
    "fields": [
      {
        "name": "name",
        "source": "data.product.name"
      },
      {
        "name": "price",
        "source": "data.product.price"
      }
    ],
    "rules": [
      {
        "field": "data.product.sku",
        "operator": "regex",
        "value": "/.*car.*/"
      }
    ],
    "headers": [
      {
        "name": "CLIENT_ID",
        "value": "abcasdf-12abcd3-45efabc4"
      }
    ]
  }
}
Copied to your clipboard
{
  "webhook": {
    "webhook_method": "observer.checkout_cart_product_add_before",
    "webhook_type": "after",
    "batch_name": "add_product",
    "batch_order": 100,
    "hook_name": "validate_product",
    "url": "https://<host>.com/validate-product-add",
    "priority": 100,
    "required": true,
    "timeout": 2000,
    "ttl": 6000,
    "soft_timeout": 1000,
    "fallback_error_message": "Unable to validate product",
    "fields": [
      {
        "name": "name",
        "source": "data.product.name"
      },
      {
        "name": "price",
        "source": "data.product.price"
      }
    ],
    "rules": [
      {
        "field": "data.product.sku",
        "operator": "regex",
        "value": "/.*car.*/"
      }
    ],
    "headers": [
      {
        "name": "CLIENT_ID",
        "value": "abcasdf-12abcd3-45efabc4"
      }
    ]
  }
}

Unsubscribe a webhook

SaaS only

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:

webhook_method
webhook_type
batch_name
hook_name

Request body

{
  "webhook": {
    "webhook_method": "observer.checkout_cart_product_add_before",
    "webhook_type": "after",
    "batch_name": "add_product",
    "hook_name": "validate_product"
  }
}
Copied to your clipboard
{
  "webhook": {
    "webhook_method": "observer.checkout_cart_product_add_before",
    "webhook_type": "after",
    "batch_name": "add_product",
    "hook_name": "validate_product"
  }
}