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.

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.

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

Including associations

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.

Deleting resources

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
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 or partially_authorized (in the latter case, multiple events are fired until the authorization balance is zero).
orders.void	An existing order payment status is set to voided or partially_voided (in the latter case, multiple events are fired until the void balance is zero).
orders.pay	An existing order payment status is set to paid or partially_paid (in the latter case, multiple events are fired until the capture balance is zero).
orders.refund	An existing order payment status is set to refunded or partially_refunded (in the latter case, multiple events are fired until the refund balance is zero).
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.cancel	An existing return status is set to cancelled.
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.refund	An existing return status is set to refunded.
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).
transactions.refused	A successful transaction has been refused by the payment gateway (i.e. the transaction succeeded attribute has changed from true to false).
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.place

• orders.approve

• orders.cancel

• orders.authorize

• orders.void

• orders.pay

• orders.refund

• orders.start_fulfilling

• orders.cancel_fulfilling

• orders.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.