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.
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
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 ↗{raw body} The request body as sent, after WooCommerce has JSON-encoded it. No timestamp is part of it.
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 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-deliverysource selected. Bodies are only logged whenWP_DEBUGis on. - WooCommerce has no way to resend a delivery. Recover missed events by fetching the data from the REST API.
Delivery behaviour
60 seconds by default; woocommerce_webhook_http_args can change it Retries none each event gets one attempt, and a failed one isn't sent again After repeated failures webhook disabled after more than 5 in a row, until you set it back to Active Ordering not documented the body is built at send time, so it shows the latest state Known failure modes
From Hookdeck's WooCommerce guide →-
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 → -
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 → -
Duplicate deliveries
Handle duplicates →order.updatedcan 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, becauseX-WC-Webhook-Delivery-IDdoesn't identify an event. -
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-IDis 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_afteron 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 | 5 | 5 |
coupon | 4 | 4 |
order | 4 | 4 |
customer | 3 | 3 |
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.