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.
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.
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 a .destroy event is triggered the resource payload sent to the webhook endpoint is simplified — since the reference resource is deleted at the time the event is fired, only the destroyed resource's id is valorized, while all of the other attributes and included relationships are null.
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:
addresses.tagged
One or more existing tags are associated with an address.
authorizations.create
An authorization transaction is created.
authorizations.succeeded
An authorization transaction has been successfully executed.
authorizations.failed
An authorization transaction failed its execution.
avalara_accounts.invoice_committed
Invoice for Avalara account gets committed.
avalara_accounts.invoice_refunded
Invoice for Avalara account gets refunded.
avalara_accounts.invoice_commit_failed
Commit for Avalara account invoice failed.
avalara_accounts.invoice_refund_failed
Refund for Avalara account invoice failed.
bundles.tagged
One or more existing tags are associated with a bundle.
buy_x_pay_y_promotions.create
A buy X pay Y promotion is created.
buy_x_pay_y_promotions.tagged
One or more existing tags are associated with a buy X pay Y promotion.
buy_x_pay_y_promotions.destroy
An existing buy_x_pay_y_promotions object is deleted.
captures.create
A capture transaction is created.
captures.succeeded
A capture transaction has been successfully executed.
captures.failed
A capture transaction failed its execution.
cleanups.create
A new cleanup is created.
cleanups.start
An existing cleanup status is set to in_progress.
cleanups.complete
An existing cleanup status is set to completed.
cleanups.interrupt
An existing cleanup status is set to interrupted.
cleanups.destroy
An existing clenups object is deleted.
coupons.tagged
One or more existing tags are associated with a coupon.
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.tagged
One or more existing tags are associated with a customer.
customers.destroy
An existing customers object is deleted.
exports.create
A new export is created.
exports.start
An existing export status is set to in_progress.
exports.complete
An existing export status is set to completed.
exports.interrupt
An existing export status is set to interrupted.
exports.destroy
An existing exports object is deleted.
external_promotions.create
An external promotion is created.
external_promotions.tagged
One or more existing tags are associated with an external promotion.
external_promotions.destroy
An existing external_promotions object is deleted.
external_promotions.failed
An existing external promotion failed to apply.
fixed_amount_promotions.create
A fixed amount promotion is created.
fixed_amount_promotions.tagged
One or more existing tags are associated with a fixed amount promotion.
fixed_amount_promotions.destroy
An existing fixed_amount_promotions object is deleted.
fixed_price_promotions.create
A fixed price promotion is created.
fixed_price_promotions.tagged
One or more existing tags are associated with a fixed price promotion.
fixed_price_promotions.destroy
An existing fixed_price_promotions object is deleted.
free_gift_promotions.create
A free gift promotion is created.
free_gift_promotions.tagged
One or more existing tags are associated with a free gift promotion.
free_gift_promotions.destroy
An existing free_gift_promotions object is deleted.
free_shipping_promotions.create
A free shipping promotion is created.
free_shipping_promotions.tagged
One or more existing tags are associated with a free shipping promotion.
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.use
A gift card is used to pay for an order.
gift_cards.tagged
One or more existing tags are associated with a gift card.
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 in_progress.
imports.complete
An existing import status is set to completed.
imports.interrupt
An existing import status is set to 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.
line_items.tagged
One or more existing tags are associated with a line item.
line_item_options.tagged
One or more existing tags are associated with a line item option.
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.placing
An existing order status is set to placing.
orders.place
An existing order status is set to placed.
orders.start_editing
An existing order status is moved from placed to editing.
orders.stop_editing
An existing order status is moved back from editing 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.create_subscriptions
An order subscription automatic generation from line items with frequency is triggered.
orders.cancel_subscriptions
An order subscription automatic cancellation due to the related source order cancellation has started.
orders.tagged
One or more existing tags are associated with an order.
orders.tax_calculation_failed
Tax calculation failed for an existing order.
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.
order_subscriptions.last_run_failed
The last run of an existing order subscription has failed.
order_subscriptions.last_run_succeeded
The last run of an existing order subscription has succeeded.
order_subscriptions.renewal
An existing order subscription is going to be renewed within the specified renewal alert period.
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.tagged
One or more existing tags are associated with a percentage discount promotion.
percentage_discount_promotions.destroy
An existing percentage_discount_promotions object is deleted.
price_frequency_tiers.create
A new price frequency tier is created.
price_frequency_tiers.destroy
An existing price_frequency_tiers object is deleted.
price_list_schedulers.activated
An existing price list scheduler has become active.
price_list_schedulers.expired
A previously active price list scheduler has expired.
price_volume_tiers.create
A new price volume tier is created.
price_volume_tiers.destroy
An existing price_volume_tiers object is deleted.
promotions.create
A new promotion is created (regardless of the type).
promotions.tagged
One or more existing tags are associated with a promotion (regardless of the type).
promotions.destroy
An existing promotions object is deleted.
recurring_order_copies.create
A new recurring order copy is created.
recurring_order_copies.destroy
An existing orders recurring_order_copies object is deleted.
recurring_order_copies.start
An existing recurring order copy started.
recurring_order_copies.fail
An existing recurring order copy failed.
recurring_order_copies.complete
An existing recurring order copy has been completed.
refunds.create
A refund transaction is created.
refunds.succeeded
A refund transaction has been successfully executed.
refunds.failed
A refund transaction failed its execution.
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.tagged
One or more existing tags are associated with a return.
returns.destroy
An existing returns object is deleted.
shipments.tagged
One or more existing tags are associated with a shipment.
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.
shipments.deliver
An existing shipment status is set to delivered.
shipping_weight_tiers.create
A new shipping weight tier is created.
shipping_weight_tiers.destroy
An existing shipping_weight_tiers object is deleted.
skus.tagged
One or more existing tags are associated with an SKU.
sku_options.tagged
One or more existing tags are associated with an SKU option.
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.on_hold
An existing stock transfer status is set to on_hold.
stock_transfers.destroy
An existing stock_transfers object is deleted
transactions.create
A new transaction is created (regardless of the type).
voids.create
A void transaction is created.
voids.succeeded
A void transaction has been successfully executed.
voids.failed
A void transaction failed its execution.
The topic of the the event the triggered the request to the callback URL is also stored in the X-CommerceLayer-Topic header of the request.
Webhooks and imports
During imports all of the real-time webhooks are disabled with the exception of some of the ones related to order status change events, namely:
orders.placeorders.approveorders.cancelorders.authorizeorders.voidorders.payorders.refundorders.start_fulfillingorders.cancel_fulfillingorders.fulfill
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
Events are automatically triggered at creation time, notifying all listening webhooks. If, for some reason, you want to force the firing of an existing event manually, you can leverage the related trigger attribute on the event resource — the event will be immediately triggered, regardless of its uniqueness.
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.
Last updated