WooCommerce webhooks

WooCommerce webhooks are HTTP POST requests a store sends to your delivery URL when a topic you've subscribed to, such as order.created, fires.

16 events covered 5 captured samples

How WooCommerce webhooks work

Webhooks push changes to your app as they happen, so you don't have to keep polling the store's REST API. Each webhook has one topic and one delivery URL. When its topic fires, WooCommerce queues the delivery and sends it in the background through Action Scheduler, so a delivery usually arrives shortly after the change and can arrive later on a quiet store.

The X-WC-Webhook-Topic header names the topic, and the JSON body is the same as the REST API's response for that resource, or just {"id": ...} for a .deleted topic. WooCommerce builds the body when it sends the delivery, so it shows the resource as it is then. Each webhook's API Version setting picks the REST version, and v3 is the default. No header or field on the delivery names that version.

Key facts

Signature header
X-WC-Webhook-Signature

Format: <base64 digest>

Scheme
HMAC-SHA256, base64

Docs discrepancy

WooCommerce's docs say a blank secret defaults to the current API user's consumer secret, and its REST docs say an MD5 hash of the user's ID and username. In WooCommerce 11.2.1, the admin form and the REST API both generate a random 50-character password instead.

Docs ↗
Signed material
{raw body}

The request body as sent, after WooCommerce has JSON-encoded it. No timestamp is part of it.

How events are identified
x-wc-webhook-topic header
Body format
JSON

Content type: application/json.

Other headers
referer, x-wc-webhook-delivery-id, x-wc-webhook-event, x-wc-webhook-id, x-wc-webhook-resource, x-wc-webhook-source, x-wc-webhook-topic
Agent skill
npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks

Verify WooCommerce webhooks →

Setting up WooCommerce webhooks

  • Create a webhook under WooCommerce > Settings > Advanced > Webhooks, or POST /wp-json/wc/v3/webhooks. Each webhook takes one topic and one delivery URL, so you'll need one per topic.
  • To test locally, use a tunnel with a public URL. WooCommerce sends through WordPress's safe HTTP request, which refuses private addresses such as localhost. See how to test WooCommerce webhooks on localhost.
  • Check deliveries under WooCommerce > Status > Logs, with the webhooks-delivery source selected. Bodies are only logged when WP_DEBUG is on.
  • WooCommerce has no way to resend a delivery. Recover missed events by fetching the data from the REST API.

Delivery behaviour

  1. Webhook disabled after failures

    WooCommerce disables a webhook after more than five consecutive failed deliveries, and core sends no alert. It stays off until you set its status back to Active, and events in between aren't sent.

    Disabled webhooks →
  2. Failed deliveries are lost

    WooCommerce makes one attempt per event and doesn't retry a failure. Fetch what you missed from the REST API once your endpoint recovers.

    Recover missed events →
  3. Duplicate deliveries

    order.updated can fire several times for one change as plugins save an order again. Skip a delivery if you've already processed the same topic and raw body, because X-WC-Webhook-Delivery-ID doesn't identify an event.

    Handle duplicates →
  4. A redirect looks like success

    WooCommerce counts a 301 or 302 as delivered and doesn't follow it, so a moved URL drops every event while the webhook stays Active. Point the delivery URL at the final address.

    Timeouts and responses →

WooCommerce webhook best practices

  • Verify every delivery. Without it, anyone who finds your URL can send fake orders. Let the unsigned ping through, because it has no topic header and doesn't carry an event.
  • Respond straight away, without a redirect. WooCommerce waits up to 60 seconds, and a slow endpoint holds up its background queue. It counts a 301 or 302 as delivered and doesn't follow it, so the event never reaches you.
  • Deduplicate on the body, not the delivery ID. X-WC-Webhook-Delivery-ID is a hash of the webhook ID and the current second, so two events can share one. Key on the topic and a hash of the raw body instead.
  • Watch for disabled webhooks. WooCommerce core sends no alert when it disables a webhook. Hook woocommerce_webhook_disabled_due_delivery_failures, or check each webhook's status on a schedule.
  • Run reconciliation jobs. A failed delivery is never sent again. Use modified_after on the orders, products and coupons endpoints to fetch what changed since the last run.
  • Run WordPress cron from your server. WP-Cron runs when someone visits the site, so a quiet store delivers late. A real cron job keeps the queue moving.

Common WooCommerce webhook events

Orders

order.created Order is created, excluding drafts
order.updated Order changes, or a refund is added or removed
order.deleted Order is moved to the trash

Products and customers

product.created Product or variation is created
product.updated Product or variation changes
customer.created Customer account is created
customer.updated Customer account changes

Coupons

coupon.created Coupon is created
coupon.updated Coupon changes

Events by resource

Resource Events Payloads
product

product.created · .updated · .deleted · .restored +1

5 5
coupon

coupon.created · .updated · .deleted · .restored

4 4
order

order.created · .updated · .deleted · .restored

4 4
customer

customer.created · .updated · .deleted

3 3

All 16 events →

In this hub

Webhook events → Every covered WooCommerce event, with payloads where the registry has them.
MCP events → How an agent subscribes to WooCommerce events as MCP events.
Verify signatures → Signature facts, verification code and common failures.
Production guide → Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
Agent skill → Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks

Keep one bad deploy from disabling your WooCommerce webhook.

Hookdeck Event Gateway accepts every WooCommerce delivery straight away, verifies the signature, queues events and retries to your service on your schedule, so a failure on your side doesn't lose the event or count against the webhook.

Not affiliated with WooCommerce. Facts are compiled from public sources and linked inline.