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.

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

SaaS Only On the Webhooks Subscriptions page, click Select > Show Logs in the Action column to display a new page that displays logging activity for that webhook. The grid resembles the Webhook Logs grid, but displays activity for the selected hook only.

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:

{
  "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:

{
  "op": "exception",
  "type": "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:

$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:

{
  "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.

$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:

$result = [
    'shipping_methods' => [
        'shipping_method_one' => [
            'amount' => 5
        ]           
    ]   
];

The response from the webhook endpoint:

{
  "op": "replace",
  "path": "result/shipping_methods/shipping_method_one/amount",
  "value": 6
}

The updated result will be modified to:

$result = [
    'shipping_methods' => [
        'shipping_method_one' => [
            'amount' => 6
        ]           
    ]   
];

Allowed instance types

The instance field of the add and replace operations accepts only data object classes, or interfaces whose implementation is a data object, such as Magento\Quote\Api\Data\ShippingMethodInterface. The class must extend Magento\Framework\DataObject or Magento\Framework\Api\AbstractSimpleObject, or implement Magento\Framework\Api\ExtensibleDataInterface. If the class is not allowed or does not exist, the operation is not applied and an error is returned.

PaaS Only To allow additional classes, add them to the allowedTypes argument of Magento\AdobeCommerceWebhooks\Model\WebhookRunner\Response\Operation\InstanceValidator in the etc/di.xml file of a custom module:

<type name="Magento\AdobeCommerceWebhooks\Model\WebhookRunner\Response\Operation\InstanceValidator">
    <arguments>
        <argument name="allowedTypes" xsi:type="array">
            <item name="my_custom_type" xsi:type="string">Vendor\Module\Api\Data\CustomTypeInterface</item>
        </argument>
    </arguments>
</type>

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:

$result = [
    'key1' => 'value1', 
    'key2' => 'value2', 
    'key3' => 'value3', 
];

The response from the webhook endpoint:

{
  "op": "remove",
  "path": "result/key2"
}

The updated result will be modified to:

$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.

Database logging

You can enable database logging for debugging webhooks from the Admin. You should not enable database logging in production environments, as it can affect the performance.

To enable database logging, navigate to Stores > Settings > Configuration > Adobe Services > Webhooks > Database logging configuration and set the Enabled option to Yes.

You can configure the minimum log level to store logs in the database and log retention time. The available log levels are DEBUG, INFO, WARNING, and ERROR.

You can also configure if you want to log the full log message. In case of an unsuccessful request, the full log message might contain response data from the external endpoint used for the webhook.

The logs are cleared once per day based on the retention time.

When database logging is enabled, the webhook logs are stored in the webhook_log table. To check logs in the Admin, navigate to System > Webhooks > Webhook Logs.

You can filter logs by multiple fields, such as webhook method, type, hook name, and request ID.