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

Published · Updated

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 overview, every topic is on WooCommerce webhook events, and signature verification code is on Verify WooCommerce webhooks.

Where WooCommerce's docs leave something out or disagree with each other, this guide follows its code at version 11.2.1, since WooCommerce is open source.

At a glance

ProblemWhat to doWith Event Gateway
TimeoutsReturn a 2xx quickly; process in a background job; don't redirectAccepts the delivery at once, then queues it for your service
DuplicatesKey on the topic and a hash of the raw body; make writes idempotentDrops repeats before they reach your handler
OrderingCompare date_modified_gmt; don't rely on arrival orderLogs every event and attempt, so you can see arrival order when debugging
RetriesWatch for disabled webhooks; reconcile from the REST APIAccepts deliveries while your service is down and retries them
Choosing topicsCreate one webhook per topic you process; read what each topic really meansFilters and routes events by topic
TestingUse a public tunnel; let the unsigned ping throughForwards to localhost and replays past events
Other limitsRun a real cron job; trim large bodies; stay on API v3Absorbs spikes and delivers at a rate you set

WooCommerce webhook timeouts and slow handlers

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

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

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.

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

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:
add_filter('woocommerce_max_webhook_delivery_failures', function() {
    return 10;
});

See how to solve WooCommerce's 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 automatically, manually or in bulk once you recover.

Choosing which WooCommerce topics to subscribe to

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.

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.

With Event Gateway: Hookdeck 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

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 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 for edge cases.

With Event Gateway: The Hookdeck 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.

Other WooCommerce webhook 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:

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 can reshape a body on the way through without any code on the store.

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.