Real-time webhooks

Commerce Layer provides a webhook mechanism to react to specific events in real-time.
To subscribe to one (or more) of those events you need to create the related webhook(s). Each time a subscribed event occurs, we trigger a POST request to the endpoint that you specified in the webhook's callback_url field. The request contains a JSON payload in the same format that you get when fetching the same resource through the REST API.
Fetching resources
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.
Including associations
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.
Callbacks security
Supported events
You can find here below the complete list of all the topics {{resource}}.{{event}} you can monitor:
Topic
Trigger
authorizations.create
A new authorization transaction is created
captures.create
A new capture transaction is created
customer_addresses.create
A new customer address is created
customer_addresses.destroy
An existing customer_addresses object is deleted
customer_password_resets.create
A customer password reset process is initiated
customer_password_resets.destroy
An existing customer_password_resets object is deleted
customer_password_resets.reset_password
A customer password is reset
customer_subscriptions.create
A new customer subscription is created
customer_subscriptions.destroy
An existing customer_subscriptions object is deleted
customers.create
A new customer is created
customers.acquired
An existing customer status is set to acquired
customers.repeat
An existing customer status is set to repeat
customers.create_password
A new password for a customer is created
customers.metadata_update
An existing customer metatdata are updated
customers.destroy
An existing customers object is deleted
external_promotions.create
An external promotion is created
external_promotions.destroy
An existing external_promotions object is deleted
fixed_amount_promotions.create
A fixed amount promotion is created
fixed_amount_promotions.destroy
An existing fixed_amount_promotions object is deleted
free_shipping_promotions.create
A free shipping promotion is created
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 of the organization.

Handling errors

Callbacks security

Last modified 21d ago

Copy link

Contents

Supported events

Responding to webhook callbacks

Handling webhook failures