# 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks` ([details](https://hookdeck.com/webhooks/woocommerce/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [WooCommerce's official docs](https://raw.githubusercontent.com/woocommerce/woocommerce-rest-api-docs/trunk/source/includes/wp-api-v3/_webhooks.md).

[Overview](https://hookdeck.com/webhooks/woocommerce) · [Webhook events (16)](https://hookdeck.com/webhooks/woocommerce/events) · [MCP events](https://hookdeck.com/webhooks/woocommerce/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/woocommerce/verify) · [Production guide](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/woocommerce/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-WC-Webhook-Signature` Format: <base64 digest> | [WooCommerce docs](https://raw.githubusercontent.com/woocommerce/woocommerce-rest-api-docs/trunk/source/includes/wp-api-v3/_webhooks.md) |
| 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](https://woocommerce.com/document/webhooks/)) | [WooCommerce docs](https://raw.githubusercontent.com/woocommerce/woocommerce-rest-api-docs/trunk/source/includes/wp-api-v3/_webhooks.md) |
| Signed material | `{raw body}` The request body as sent, after WooCommerce has JSON-encoded it. No timestamp is part of it. | [WooCommerce docs](https://raw.githubusercontent.com/woocommerce/woocommerce-rest-api-docs/trunk/source/includes/wp-api-v3/_webhooks.md) |
| How events are identified | `x-wc-webhook-topic header` | [WooCommerce docs](https://raw.githubusercontent.com/woocommerce/woocommerce-rest-api-docs/trunk/source/includes/wp-api-v3/_webhooks.md) |
| Body format | `JSON` Content type: application/json. | [WooCommerce docs](https://raw.githubusercontent.com/woocommerce/woocommerce-rest-api-docs/trunk/source/includes/wp-api-v3/_webhooks.md) |
| 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` | [Registry record](https://hookdeck.com/webhooks/woocommerce.json) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill woocommerce-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/woocommerce/skill) |

[Verify WooCommerce webhooks](https://hookdeck.com/webhooks/woocommerce/verify)

## 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.

## 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](https://developer.wordpress.org/reference/functions/wp_http_validate_url/). See [how to test WooCommerce webhooks on localhost](/webhooks/platforms/how-to-test-and-replay-woocommerce-webhook-events-on-localhost-with-hookdeck).
- 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

- **Timeout:** 60 seconds. by default; `woocommerce_webhook_http_args` can change it. [Guide](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** none. each event gets one attempt, and a failed one isn't sent again. [Guide](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#retries)
- **After repeated failures:** webhook disabled. after more than 5 in a row, until you set it back to Active. [Guide](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not documented. the body is built at send time, so it shows the latest state. [Guide](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#timeouts)

From [Hookdeck's WooCommerce guide](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts).

## WooCommerce webhook best practices

- **[Verify every delivery](https://hookdeck.com/webhooks/woocommerce/verify).** 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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#duplicates).** `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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/woocommerce/guide-duplicates-ordering-retries-timeouts#other-limits).** 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](https://hookdeck.com/webhooks/woocommerce/events#order.created): Order is created, excluding drafts
- [order.updated](https://hookdeck.com/webhooks/woocommerce/events#order.updated): Order changes, or a refund is added or removed
- [order.deleted](https://hookdeck.com/webhooks/woocommerce/events#order.deleted): Order is moved to the trash

### Products and customers

- [product.created](https://hookdeck.com/webhooks/woocommerce/events#product.created): Product or variation is created
- [product.updated](https://hookdeck.com/webhooks/woocommerce/events#product.updated): Product or variation changes
- [customer.created](https://hookdeck.com/webhooks/woocommerce/events#customer.created): Customer account is created
- [customer.updated](https://hookdeck.com/webhooks/woocommerce/events#customer.updated): Customer account changes

### Coupons

- [coupon.created](https://hookdeck.com/webhooks/woocommerce/events#coupon.created): Coupon is created
- [coupon.updated](https://hookdeck.com/webhooks/woocommerce/events#coupon.updated): Coupon changes

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [product](https://hookdeck.com/webhooks/woocommerce/events#resource-product) | 5 | 5 |
| [coupon](https://hookdeck.com/webhooks/woocommerce/events#resource-coupon) | 4 | 4 |
| [order](https://hookdeck.com/webhooks/woocommerce/events#resource-order) | 4 | 4 |
| [customer](https://hookdeck.com/webhooks/woocommerce/events#resource-customer) | 3 | 3 |

[All 16 events](https://hookdeck.com/webhooks/woocommerce/events)

## In this hub

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

Not affiliated with WooCommerce. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/woocommerce.json) · [Report a correction](https://hookdeck.com/contact)
