Webhooks
Overview
Live Carts for WooCommerce implements a webhook subscription system that POSTs a signed JSON payload to external URLs when cart/list events happen.
Requirements
The webhooks feature requires a recent version of Live Carts for WooCommerce (free). The Pro version is not required for the webhooks functionality.
Configuration
Configure webhooks from Live Carts → Settings → API (see API Settings). Each webhook has:
- a URL to POST to,
- one or more events it's subscribed to (below),
- a secret, generated automatically and used to sign payloads,
- an active flag.
Events
| Event | Fires when | Payload |
|---|---|---|
cart.created | A new cart is first tracked. | cart |
cart.seen | A cart is seen on a new request (also re-marks an abandoned cart active). | cart |
cart.items.added | A line item is newly present in a cart (one event per item). | cart + item |
cart.items.removed | A line item is no longer in a cart (one event per item; item is its last known state). | cart + item |
cart.items.updated | An existing line item's quantity changes (one event per item). | cart + item + item_before |
cart.converted | A cart's linked order reaches a "converted" order status. | cart |
cart.abandoned | The hourly cron job marks an inactive cart abandoned. | cart |
list.created | A shopper list is first tracked for a user. | list |
list.seen | A shopper list is seen on a new request. | list |
list.items.added | An item is added to a shopper list (one event per item). | list + item |
list.items.removed | An item is removed from a shopper list (one event per item). | list + item |
list.items.updated | A shopper list item's quantity changes (one event per item). | list + item + item_before |
Each event is only dispatched when at least one active webhook is actually subscribed to it.
Note: The cart.seen and list.seen events may be fired very frequently and frontend impacts should be considered before subscribing to these events.
Delivery
On each event, Live Carts sends a POST request to every active webhook
subscribed to that event:
POST <webhook url>
Content-Type: application/json
X-Live-Carts-Event: cart.items.added
X-Live-Carts-Signature: <hex-encoded HMAC-SHA256 of the raw body, keyed with the webhook's secret>
A cart event's payload carries a cart key; a list event's payload
carries a list key instead. These objects match what
GET /carts/{id} or GET /shopper-lists/{id} returns for the same
resource - see the REST API reference.
For the item events (cart.items.* / list.items.*), the payload
also carries an item field — in the same format as a revision's
changes[].item in GET /carts/{id} — describing the item that
was added, removed, or changed. One event fires per item changed, not
one batched event for the whole cart/list update. *.items.updated also
includes item_before, the item as it was immediately prior to the change.
Verify authenticity by recomputing the HMAC of the raw request body with
the webhook's secret and comparing it to X-Live-Carts-Signature.
Delivery is fire-and-forget: the request is sent non-blocking to avoid delaying the shopper's request, there is no retry on failure, and no delivery log is kept. Your endpoint should return quickly and idempotently handle duplicate deliveries.