# WooCommerce webhooks in production: duplicates, ordering, retries and timeouts

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

This guide covers the problems WooCommerce webhooks cause in production and how to handle each one. What WooCommerce sends and how it's signed is on the [WooCommerce webhooks](/webhooks/woocommerce) overview, every topic is on [WooCommerce webhook events](/webhooks/woocommerce/events), and signature verification code is on [Verify WooCommerce webhooks](/webhooks/woocommerce/verify).

Where WooCommerce's docs leave something out or disagree with each other, this guide follows [its code at version 11.2.1](https://github.com/woocommerce/woocommerce/blob/11.2.1/plugins/woocommerce/includes/class-wc-webhook.php), since WooCommerce is open source.

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Return a 2xx quickly; process in a background job; don't redirect | Accepts the delivery at once, then queues it for your service |
| [Duplicates](#duplicates) | Key on the topic and a hash of the raw body; make writes idempotent | Drops repeats before they reach your handler |
| [Ordering](#ordering) | Compare `date_modified_gmt`; don't rely on arrival order | Logs every event and attempt, so you can see arrival order when debugging |
| [Retries](#retries) | Watch for disabled webhooks; reconcile from the REST API | Accepts deliveries while your service is down and retries them |
| [Choosing topics](#choosing-events) | Create one webhook per topic you process; read what each topic really means | Filters and routes events by topic |
| [Testing](#testing) | Use a public tunnel; let the unsigned ping through | Forwards to localhost and replays past events |
| [Other limits](#other-limits) | Run a real cron job; trim large bodies; stay on API v3 | Absorbs spikes and delivers at a rate you set |

## WooCommerce webhook timeouts and slow handlers {#timeouts}

Return a 2xx status quickly, then do the work in a background job. Don't answer with a redirect.

**Why it happens:** WooCommerce waits up to 60 seconds for a response by default. That's long compared with most platforms, but your handler shouldn't use it. Deliveries run from Action Scheduler, which by default [processes actions in a single concurrent queue for about 30 seconds per request](https://actionscheduler.org/perf/), so a slow endpoint holds up the store's other background work. A timeout counts as a failed delivery.

WooCommerce treats 2xx, 301 and 302 responses as success, and it sends with redirects turned off. A 301 or 302 therefore counts as delivered without the event reaching anything. A delivery URL that redirects, for instance from HTTP to HTTPS or to add a trailing slash, can lose every event while the webhook stays Active and its failure count stays at zero.

**Fix it in your handler:**

1. Verify the signature and return 200 straight away.
2. Push the event onto a queue and process it in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
3. Set the delivery URL to the final address, and check for a 2xx in the `webhooks-delivery` log after you save it.

**With Event Gateway:** Hookdeck accepts each WooCommerce delivery immediately, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take as long as it needs without failing a WooCommerce delivery or slowing the store's queue.

## Duplicate WooCommerce webhooks {#duplicates}

WooCommerce doesn't deduplicate across requests, so one change can produce several deliveries. Skip a delivery if you've already processed the same topic and raw body, and make your writes idempotent.

**Why it happens:** `order.updated` fires each time an order is saved, and also when a refund is added or removed. Plugins and payment gateways often save an order several times, in separate requests. WooCommerce only suppresses repeats for the same webhook and resource within a single request, or while an earlier delivery is still waiting in the queue. Once that delivery starts, the next save queues another. Two webhooks with the same topic and URL also each send their own delivery.

Don't deduplicate on `X-WC-Webhook-Delivery-ID`. WooCommerce generates it as a hash of the webhook ID and the current time in seconds, so two different events on one webhook in the same second get the same ID, and you'd drop the second one. `X-WC-Webhook-ID` is the webhook's own ID and is the same on every delivery from that webhook. A unique constraint on the order ID and topic is also wrong, because it discards every later `order.updated` for that order.

**Fix it in your handler:**

1. Hash the topic and raw body, and skip the delivery if you've seen that hash recently. An identical body means nothing has changed, so you can't lose information this way. Give the key an expiry, because a `.deleted` body holds only the ID, and the same item can be trashed again after a restore.
2. Write with upserts keyed on the resource `id`, so processing the same state twice gives the same result. See [how to implement webhook idempotency](/webhooks/guides/implement-webhook-idempotency).
3. Before a side effect such as sending an email, check whether the state it depends on has actually changed. `status` is the usual one for orders.

```python
def handle_woocommerce_delivery(raw_body, topic):
    key = hashlib.sha256(topic.encode() + b":" + raw_body).hexdigest()

    # Same topic and same body already processed
    if not cache.set(f"wc_delivery_{key}", True, nx=True, ex=86400):
        return

    process(json.loads(raw_body))

```

**With Event Gateway:** Hookdeck [deduplicates](/docs/deduplication) events before they reach your endpoint, on the whole payload or on fields you choose, so repeats are filtered at the infrastructure level rather than in each handler.

## Out-of-order WooCommerce webhooks {#ordering}

WooCommerce's docs say nothing about delivery order, so don't rely on it. Compare the body's `date_modified_gmt` with what you've stored, and ignore anything older.

**Why it happens:** Each delivery is a separate action in a background queue, and a failed one is never sent again. WooCommerce builds the body when it sends the delivery, not when the topic fires. An `order.created` delivery that waits in the queue can show the order's later status, and saves made while a delivery is waiting are merged into it. You won't see every intermediate state, so don't build a state machine that expects each one. For more on the general problem, see [Webhook Ordering: Why It's Hard and How to Handle It](/webhooks/guides/webhook-ordering-why-its-hard-and-how-to-handle-it).

**Fix it in your handler:**

1. Store `date_modified_gmt` with each resource, and ignore a delivery older than what you have.
2. Treat the body as the current state of the resource, rather than a record of one change.
3. When the state matters, fetch the resource from the REST API before acting on it.
4. Handle a `.deleted` delivery by `id` alone, since that's all its body holds.

**With Event Gateway:** Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.

## WooCommerce webhook retries and disabled webhooks {#retries}

WooCommerce doesn't retry a failed delivery, and after more than five consecutive failures it disables the webhook. Watch for disabled webhooks, and reconcile from the REST API after any outage.

**Why it happens:** WooCommerce sends each event once. A failed delivery only adds one to the webhook's failure count, and a success resets it to zero. Any response other than a 2xx, 301 or 302 counts as a failure, as do timeouts and connection errors. One WooCommerce docs page says webhooks are disabled "after 5 retries", but the code doesn't make any.

The docs give the limit as 5 or "more than five". In the code the check runs before the count goes up, so the seventh consecutive failure is the one that disables the webhook. A short outage on a busy store gets there in minutes. While a webhook is disabled it doesn't send anything, and those events aren't queued for later. WooCommerce core fires an action when this happens but sends no alert.

**Fix it in your handler:**

1. Alert on it. Hook `woocommerce_webhook_disabled_due_delivery_failures`, or poll `GET /wp-json/wc/v3/webhooks` and check each `status`.
2. After a fix, set the webhook back to Active in the admin or through the REST API. The failure count isn't reset until a delivery succeeds, so the first failure after you re-enable it disables it again.
3. Reconcile on a schedule and after every outage. The orders, products and coupons endpoints accept `modified_after`, so you can fetch what changed since your last run.
4. If you need more tolerance, raise the limit. This only delays the disable, and each failed event is still lost:

```php
add_filter('woocommerce_max_webhook_delivery_failures', function() {
    return 10;
});

```

See [how to solve WooCommerce's 5-delivery-failure webhook disabling](/webhooks/platforms/how-to-solve-woocommerce-5-delivery-failure-webhook-disabling) for more on this.

**With Event Gateway:** Hookdeck captures every WooCommerce delivery while your services are down, so WooCommerce's deliveries succeed and the webhook isn't disabled. Failed events can be [retried](/docs/retries) automatically, manually or in bulk once you recover.

## Choosing which WooCommerce topics to subscribe to {#choosing-events}

Create a webhook for each topic your integration processes, and check what a topic means before you rely on it. The full list, with sample payloads, is on [WooCommerce webhook events](/webhooks/woocommerce/events).

**Why it matters:** Each webhook has one topic and every delivery has a cost on the store's queue, so a broad `order.updated` listener is often more traffic than an integration needs. Some topics also don't mean what their names suggest:

* `order.created` doesn't mean paid. An order can be created before payment completes, so check `status`.
* Refunds arrive as `order.updated`. There's no separate refund topic.
* `order.deleted`, `product.deleted` and `coupon.deleted` fire when an item moves to the trash, and their bodies hold only the `id`. In 11.2.1, a permanent delete that skips the trash isn't one of the hooks these topics listen to.
* `customer.deleted` only fires for users with the `customer` role.
* `coupon.restored`, `order.restored` and `product.restored` are in WooCommerce's admin dropdown and code but not in its REST docs' list. `product.published` needs WooCommerce 10.8 or later.

**Fix it in your handler:**

1. List the topics your code handles, and create exactly those webhooks. Check `X-WC-Webhook-Topic` and ignore anything you don't expect, because extensions can add topics.
2. For a custom event, use an action topic such as `action.woocommerce_add_to_cart`. The name must start with `action.woocommerce_` or `action.wc_`. The body is `{"action": ..., "arg": ...}`, where `arg` is the hook's first argument.
3. Remove fields you don't need with the `woocommerce_webhook_payload` filter. See [other limits](#other-limits).

**With Event Gateway:** Hookdeck [filters](/docs/filters) and routes events by topic or any other property, so several WooCommerce webhooks can point at one source and feed different services.

## Testing and debugging WooCommerce webhooks {#testing}

Send deliveries through a public tunnel to reach your local server, and test that your handler accepts the ping.

**Why it happens:** WooCommerce sends with WordPress's safe HTTP functions, and [WordPress's URL check](https://developer.wordpress.org/reference/functions/wp_http_validate_url/) refuses private addresses such as localhost and ports other than 80, 443 and 8080. A delivery URL on your own machine therefore fails unless the store runs there too.

The first time you save a webhook as Active, WooCommerce sends a ping. Its body is `webhook_id=<id>`, it isn't JSON, and it has no `X-WC-Webhook-*` headers, so a handler that parses JSON or requires a signature rejects it. A failed ping shows an error in the admin but doesn't stop deliveries. In 11.2.1 WooCommerce pings again each time it saves that webhook until a ping gets a 200, and it saves after every delivery, so you'll keep seeing pings until you accept one.

**Fix it in your setup:**

1. Point the webhook at a public URL that forwards to your machine, then trigger the real action: create an order, or update a product.
2. Return 200 to a request with no `X-WC-Webhook-Topic` header, without processing it.
3. Read delivery results under WooCommerce > Status > Logs, with the `webhooks-delivery` source selected. Request and response bodies are only logged when `WP_DEBUG` is on, so log what you receive on your side too.
4. Test verification with a missing signature, a tampered body and a wrong secret, and keep fixtures from [WooCommerce webhook events](/webhooks/woocommerce/events) for edge cases.

**With Event Gateway:** The [Hookdeck CLI](/docs/cli) receives webhooks on your machine through a public URL, and you can replay past events. See [how to test and replay WooCommerce webhooks locally](/webhooks/platforms/how-to-test-and-replay-woocommerce-webhook-events-on-localhost-with-hookdeck).

## Other WooCommerce webhook limits {#other-limits}

Plan for background delivery delays, queue backlogs, large bodies and API versions before they reach production.

**Late deliveries.** WooCommerce queues deliveries in Action Scheduler, which is started by WP-Cron, and WP-Cron only runs when someone visits the site. A quiet store can deliver minutes late. Run WordPress cron from a server cron job every minute. You can also make WooCommerce send during the request with `add_filter('woocommerce_webhook_deliver_async', '__return_false')`, but a slow endpoint then slows the request that triggered it, including checkout.

**Queue backlogs.** High-volume stores can build up pending `woocommerce_deliver_webhook_async` actions, which delays deliveries and uses database resources. Run the queue more often from server cron, raise Action Scheduler's concurrency, and clear actions you don't need.

**Large bodies.** Orders with many line items or custom fields make large bodies. Your server needs to accept them, and you can trim them with the `woocommerce_webhook_payload` filter:

```php
add_filter('woocommerce_webhook_payload', function($payload, $resource, $resource_id, $id) {
    if ($resource === 'order') {
        unset($payload['meta_data']);
        unset($payload['billing']['phone']);
    }
    return $payload;
}, 10, 4);

```

The same filter can add fields, for example with `$order->get_meta()`. Bodies that are filtered this way no longer match the REST API's response, so a shared parser needs to allow for that.

**API versions.** Each webhook chooses WP REST API v1, v2 or v3, and v3 is the default. Use v3 unless an existing integration needs another. Legacy API v3 only works where the separate Legacy REST API is available. Without it, a webhook still set to that version fails to deliver until you edit it. No delivery header says which version a body uses, so if you migrate, change the webhook and your parser together.

**With Event Gateway:** Hookdeck absorbs spikes in its queue and delivers at a rate you configure, and its [transformations](/docs/transformations) can reshape a body on the way through without any code on the store.