Real-time webhooks

Commerce Layer provides a webhook mechanism to react to specific events in real-time.
Each time a subscribed event occurs, we trigger a POST request to the endpoint that you specified in the 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
free_shipping_promotions.destroy
An existing free_shipping_promotions object is deleted
gift_cards.create
A new gift card is created
gift_cards.purchase
An existing gift card is purchased
gift_cards.activate
An existing gift card status is set to active
gift_cards.deactivate
An active gift card status is set to inactive
gift_cards.redeem
An existing gift card status is set to redeemed
gift_cards.destroy
An existing gift_cards object is deleted
imports.create
A new import is created
imports.start
An existing import status is set to started
imports.complete
An existing import status is set to completed
imports.interrupt
An existing import is interrupted
imports.destroy
An existing imports object is deleted
in_stock_subscriptions.create
A new in-stock subscription is created
in_stock_subscriptions.activate
An existing in-stock subscription status is set to active
in_stock_subscriptions.deactivate
An existing in-stock subscription status is set to inactive
in_stock_subscriptions.notify
An existing in-stock subscription status is set to notified
in_stock_subscriptions.destroy
An existing in_stock_subscriptions object is deleted
orders.create
A new order is created
orders.draft
An existing order status is set to draft
orders.pending
An existing order status is set to pending
orders.place
An existing order status is set to placed
orders.approve
An existing order status is set to approved
orders.cancel
An existing order status is set to cancelled
orders.authorize
An existing order payment status is set to authorized
orders.void
An existing order payment status is set to voided
orders.pay
An existing order payment status is set to paid
orders.refund
An existing order payment status is set to refunded
orders.start_fulfilling
An existing order fulfillment status is set to in_progress
orders.cancel_fulfilling
An existing order with fulfillment status in_progress is cancelled.
orders.fulfill
An existing order fulfillment status is set to fulfilled
orders.rebuild_shipments
An existing order's shipments are rebuilt
orders.destroy
An existing orders object is deleted
order_copies.create
A new order copy is created
order_copies.destroy
An existing orders order_copies object is deleted
order_copies.start
An existing order copy started
order_copies.fail
An existing order copy failed
order_copies.complete
An existing order copy has been completed
order_subscriptions.create
A new order subscription is created
order_subscriptions.destroy
An existing orders order_subscriptions object is deleted
order_subscriptions.activate
An existing order subscription has been activated
order_subscriptions.deactivate
An existing order subscription has been deactivated
order_subscriptions.cancel
An existing order subscription has been cancelled
parcels.create
A new parcel is created
parcels.destroy
An existing orders parcels object is deleted
parcels.pre_transit
An existing parcel tracking status is set to pre_transit
parcels.in_transit
An existing parcel tracking status is set to in_transit
parcels.out_for_delivery
An existing parcel tracking status is set to out_for_delivery
parcels.delivered
An existing parcel tracking status is set to delivered
parcels.shipped
An existing parcel tracking status is set to shipped
parcels.available_for_pickup
An existing parcel tracking status is set to available_for_pickup
parcels.booked
An existing parcel tracking status is set to booked
parcels.return_to_sender
An existing parcel tracking status is set to return_to_sender
parcels.cancelled
An existing parcel tracking status is set to cancelled
parcels.failure
An existing parcel tracking status is set to failure
percentage_discount_promotions.create
A new percentage discount promotion is created
percentage_discount_promotions.destroy
An existing percentage_discount_promotion object is deleted
refunds.create
A new refund is created
returns.create
A new return is created
returns.request
An existing return status is set to requested
returns.pending
An existing return status is set to pending
returns.approve
An existing return status is set to approved
returns.reject
An existing return status is set to rejected
returns.ship
An existing return status is set to shipped
returns.receive
An existing return status is set to received
returns.restock
An existing return's line items are restocked
returns.destroy
An existing returns object is deleted
shipments.upcoming
An existing shipment status is set to upcoming
shipments.cancel
An existing shipment status is set to cancelled
shipments.on_hold
An existing shipment status is set to on_hold
shipments.picking
An existing shipment status is set to picking
shipments.packing
An existing shipment status is set to packing
shipments.ready_to_ship
An existing shipment status is set to ready_to_ship
shipments.ship
An existing shipment status is set to shipped
stock_transfers.create
A new stock transfer is created
stock_transfers.upcoming
An existing stock transfer status is set to upcoming
stock_transfers.picking
An existing stock transfer status is set to picking
stock_transfers.in_transit
An existing stock transfer status is set to in_transit
stock_transfers.complete
An existing stock transfer status is set to completed
stock_transfers.cancel
An existing stock transfer status is set to cancelled
stock_transfers.destroy
An existing stock_transfers object is deleted
voids.create
A new void transaction 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 1mo ago

Copy link

Contents

Supported events

Responding to webhook callbacks

Handling webhook failures