Real-time webhooks

The complete list of supported events for each resource

Commerce Layer provides a webhook mechanism to react to specific events in real-time.

For each resource, you can also configure the related resources that should be included in the request body. The relationships will be set as the resource include query parameter.

When a tagged event is triggered, the related tag(s) are automatically included in the callback's payload, as relationships of the tagged resource.

When you create a new webhook, a shared secret is generated. It will be used each time the webhook is fired to sign the payload. The related signature will be stored in the X-CommerceLayer-Signature header so that you can verify the callback authenticity and consider it reliable.

Supported events

You can find here below the complete list of all the topics {{resource}}.{{event}} you can monitor:

Excluding those associated with order status change events (orders.place, orders.approve, orders.cancel, orders.authorize, orders.void, orders.pay, orders.refund, orders.start_fulfilling, orders.cancel_fulfilling, and orders.fulfill), during imports all of the real-time webhooks are disabled.

In case you need to leverage all the other real-time events you have to create/update resources via the related API endpoints.

Retriggering events

Responding to webhook callbacks

The endpoint listening for webhooks has 5 seconds to respond with a 2xx (usually 200 ) response code, acknowledging a successful delivery. If the request times out or gets a response with a status code other than 2xx, it is considered failed.

Handling webhook failures

If a webhook fails (whatever the reason) Commerce Layer tries to fire it again up to 10 times. After 30 consecutive failures (retry failures included) no further calls to the related endpoint are made and the webhook has to be reset.

To let you properly handle this scenario and inspect the reasons for the failure, after 5 consecutive non-successful attempts a communication is sent to the owner and all the admins of the organization.