Webhook responses and logging

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. Each operation must contain some required fields based on the desired operation.

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

Responses

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.

Adobe Commerce webhooks support the following operations:

Success operation

The success operation is returned when changes are not needed. The process that triggered the original event continues without any changes.

The response of a successful request is as follows:

Copy
{
  "op": "success"
}
Copied to your clipboard
{
  "op": "success"
}

Exception operation

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.

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

Copy
{
  "op": "exception",
  "class": "Path\\To\\Exception\\Class",
  "message": "The product cannot be added to the cart because it is out of the stock"
}
Copied to your clipboard
{
  "op": "exception",
  "class": "Path\\To\\Exception\\Class",
  "message": "The product cannot be added to the cart because it is out of the stock"
}

Add operation

The add operation causes Commerce to add the provided value to the provided path to the triggered event arguments

For example, we want to add a new shipping method to the triggered event result payload. The result is an array of Magento\Quote\Model\Cart\ShippingMethod objects:

Copy
$result = [
    0 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
    1 => {Magento\Quote\Model\Cart\ShippingMethodInterface}
];
Copied to your clipboard
$result = [
    0 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
    1 => {Magento\Quote\Model\Cart\ShippingMethodInterface}
];

To add a new shipping method to that result, the response from the webhook would look like:

Copy
{
  "op": "add",
  "path": "result",
  "value": {
    "data": {
      "amount": "5",
      "base_amount": "5",
      "carrier_code": "newshipmethod",
      "carrier_title": "Webhook new shipping method",
    }
  },
  "instance": "Magento\\Quote\\Api\\Data\\ShippingMethodInterface"
}
Copied to your clipboard
{
  "op": "add",
  "path": "result",
  "value": {
    "data": {
      "amount": "5",
      "base_amount": "5",
      "carrier_code": "newshipmethod",
      "carrier_title": "Webhook new shipping method",
    }
  },
  "instance": "Magento\\Quote\\Api\\Data\\ShippingMethodInterface"
}

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.

Copy
$result = [
    0 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
    1 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
    2 => {Magento\Quote\Model\Cart\ShippingMethodInterface}
];
Copied to your clipboard
$result = [
    0 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
    1 => {Magento\Quote\Model\Cart\ShippingMethodInterface},
    2 => {Magento\Quote\Model\Cart\ShippingMethodInterface}
];

Replace operation

The replace operation causes Commerce to replace a value in triggered event arguments for the provided path

The following example replaces a nested element in the triggered event result payload:

Copy
$result = [
    'shipping_methods' => [
        'shipping_method_one' => [
            'amount' => 5
        ]           
    ]   
];
Copied to your clipboard
$result = [
    'shipping_methods' => [
        'shipping_method_one' => [
            'amount' => 5
        ]           
    ]   
];

The response from the webhook endpoint:

Copy
{
  "op": "replace",
  "path": "result/shipping_methods/shipping_method_one/amount",
  "value": 6
}
Copied to your clipboard
{
  "op": "replace",
  "path": "result/shipping_methods/shipping_method_one/amount",
  "value": 6
}

The updated result will be modified to:

Copy
$result = [
    'shipping_methods' => [
        'shipping_method_one' => [
            'amount' => 6
        ]           
    ]   
];
Copied to your clipboard
$result = [
    'shipping_methods' => [
        'shipping_method_one' => [
            'amount' => 6
        ]           
    ]   
];

Remove operation

The remove operation causes Commerce to remove a value or node in triggered event arguments by the provided path

The following example removes element key2 from the triggered event result payload:

Copy
$result = [
    'key1' => 'value1', 
    'key2' => 'value2', 
    'key3' => 'value3', 
];
Copied to your clipboard
$result = [
    'key1' => 'value1', 
    'key2' => 'value2', 
    'key3' => 'value3', 
];

The response from the webhook endpoint:

Copy
{
  "op": "remove",
  "path": "result/key2"
}
Copied to your clipboard
{
  "op": "remove",
  "path": "result/key2"
}

The updated result will be modified to:

Copy
$result = [
    'key1' => 'value1', 
    'key3' => 'value3', 
];
Copied to your clipboard
$result = [
    'key1' => 'value1', 
    'key3' => 'value3', 
];

Logging

The following table describes webhook logging activity. Each hook can be configured to have its own soft and hard timeout values.

Last updated 11/9/2023

Was this helpful?

Yes

No