WordPress.com webhooks in production: duplicates, retries and timeouts
This guide covers the problems WordPress.com's built-in webhooks cause in production and how to handle each one. These are the webhooks you set up at /wp-admin/options-general.php?page=webhooks on a WordPress.com site. They don't apply to plugin-enabled sites, and self-hosted WordPress and WooCommerce are different systems. What WordPress.com sends is on the WordPress.com webhooks overview, the three actions are on WordPress.com webhook events, and how to protect an unsigned endpoint is on Verify WordPress.com webhooks.
WordPress.com documents this feature on one support page, which says little about delivery. Where the docs are silent, this guide says so and plans for the cautious reading.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 2xx first; do the work in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Key on hook, ID and post_modified_gmt; make handlers idempotent | Deduplicates on the fields you choose, as a first filter |
| Retries | Stay available; log what you receive; reconcile from the REST API | Accepts deliveries while your service is down, retries and replays them |
| Choosing events | Create one webhook per action; select only the fields you need | Filters and routes events by action |
| Testing | Trigger a real action and capture the delivery before writing your parser | Forwards to localhost and replays past events |
| Other limits | Protect the URL yourself; check the feature applies to your site | Signs what it forwards, and can require an API key on a generic Source |
WordPress.com webhook timeouts and slow handlers
WordPress.com's docs don't give a timeout, so return a 2xx as soon as you've checked your URL token and do the rest in a background job.
Why it happens: The docs say the URL receives an HTTP POST when the action fires, and stop there. They don't say how long WordPress.com waits, which status codes count as success, or whether a slow response holds up the publish. WordPress.com built the feature from the HookPress plugin, and HookPress sends its request from inside the WordPress action. WordPress.com also says it trimmed features during that work to protect performance, so HookPress's behaviour is a lead and not a fact about WordPress.com.
Fix it in your handler:
- Check the token and return a 2xx straight away.
- Push the delivery onto a queue and process it in a worker. See why to process webhooks asynchronously.
- Log each request's arrival time and your response, because the docs describe no delivery log on WordPress.com's side.
With Event Gateway: Hookdeck accepts each WordPress.com delivery immediately, then queues events and delivers them to your service, so your handler can take as long as it needs.
Duplicate WordPress.com webhooks
publish_post and publish_page fire again each time a published item is edited, so the same ID can arrive many times. Make your handler safe to run twice, and key on hook, ID and post_modified_gmt.
Why it happens: WordPress.com runs both actions when an item is published, and again if it's edited while its status is published. A repeat is usually a real edit rather than a redelivery. No delivery ID or event ID is documented, and neither is any retry behaviour, so you can't rule out a second delivery of the same state.
Fix it in your handler:
- Select
IDandpost_modified_gmton the webhook. Only selected fields are sent, so without them you have nothing stable to key on. - For
comment_post, selectcomment_IDand key on that. - Upsert on
ID, or record each key in a table with a unique constraint, so that every handler is idempotent. - To act only on the first publish, keep a record of the IDs you've seen. The docs describe no field that separates a first publish from an edit.
With Event Gateway: Hookdeck can deduplicate on the whole event or on fields you choose, within a window of up to an hour. Use it to cut noise from repeated saves, and keep your handler idempotent as well, because deduplication is best-effort.
Failed and missed WordPress.com webhooks
WordPress.com's docs describe no retries, no delivery log and no way to resend, so plan as if a delivery your endpoint misses won't come back.
Why it happens: The page covers adding, editing, deleting and deactivating a webhook, and says nothing about what happens when a delivery fails. That doesn't prove there are no retries, but you can't rely on any. The docs also don't say whether repeated failures turn a webhook off.
Fix it in your handler:
- Log every delivery and alert when they stop arriving, since WordPress.com's docs describe no failure alert.
- Run a reconciliation job against the REST API. The posts endpoint takes
modified_after, and the comments endpoint takesafter. Fetch what changed since your last good run and upsert it. - After an outage, check that the webhook's row still shows it as active.
With Event Gateway: Hookdeck accepts deliveries while your service is down, then retries on a schedule you set, and logs every attempt. Events that run out of retries stay available to inspect and replay. See dead-letter queues for webhooks.
Choosing WordPress.com webhook events
WordPress.com lists three actions: publish_post, publish_page and comment_post. Anything else, such as a deleted post or a new user, needs another route.
Why it happens: Those are the only rows in the docs' actions table. Each webhook takes one action and the fields you select for it, and a delivery holds those fields plus hook. There's no fixed envelope beyond that one field.
Fix it in your handler:
- Create one webhook per action and dispatch on
hook. - Select the fields your handler reads, and guard every access, because an admin can change the selection later.
- Leave out what you don't need.
post_password,comment_author_emailandcomment_author_IPare selectable, and if you select them they'll reach your endpoint and possibly your logs. - For
comment_post, the field list hascomment_post_IDbut no post title or URL. Fetch the post from the REST API in your worker. - Check
comment_approvedbefore you show a comment, because the action runs when a comment is saved. In WordPress core, the value is1if approved,0if not, andspamfor spam. - Poll the REST API for changes the three actions don't cover.
With Event Gateway: Hookdeck filters and routes events by their content, so each service gets only the actions it handles. Filters are designed for JSON, so if your deliveries arrive as form data, run a transformation that converts them first. Transformations can't make network calls, so post lookups stay in your worker.
Testing WordPress.com webhooks
WordPress.com's docs describe no test button and publish no example body, so trigger a real action and capture the delivery before you write your parser.
Why it matters: The docs don't name a content type, don't show how an array field such as post_category is encoded, and don't list any headers. HookPress form-encodes its fields, so expect form data, but only a real delivery settles it.
How to test it:
- Point a webhook at a temporary URL, such as Hookdeck Inspect, and select every field you plan to read.
- Publish a test post or page, edit it for a second delivery, and submit a comment.
- Read the
Content-Type, the headers and the body, then base your parser on those. - Select
post_categoryand publish a post in more than one category, to see how the array arrives. - Add your token to the URL and confirm that it arrives, because the docs don't mention query strings.
- Take your endpoint down, publish something, and see whether it ever arrives. The docs don't say, and this tells you what to plan for.
With Event Gateway: The Hookdeck CLI gives you a stable URL that sends webhooks to your machine: run hookdeck listen 3000 wordpress-com --path /webhooks/wordpress-com, then replay past events instead of publishing another test post.
Other WordPress.com webhook limits
Plan for the missing signature, the plugin restriction and the admin-only setup before they reach production.
No signature. The webhook form takes an action, fields and a URL, with no secret or signature option, and the docs publish no IP ranges for this feature. Protect the endpoint yourself with a long random token in the URL, HTTPS, and a re-fetch from the REST API before anything important. Treat the token as exposed to anyone who can open the webhook settings or read your access logs, and rotate it when that matters. The code is on Verify WordPress.com webhooks.
Plugin-enabled sites. WordPress.com says these settings don't apply to plugin-enabled sites, and that various plugins offer something similar, so check that the setting exists on your site before you design around it.
Self-hosted WordPress and WooCommerce are different systems. Self-hosted WordPress needs a plugin such as WP Webhooks. WooCommerce has its own webhooks, signed with X-WC-Webhook-Signature, and nothing about them applies to the feature in this guide.
Setup is by hand. Only admin-level users can add or manage webhooks, and the docs describe no API for doing it. If you run several sites, keep each webhook's action, fields and URL in your runbook.
With Event Gateway: Hookdeck can't verify that a delivery came from WordPress.com, because there's no signature to check. A generic Source can require an API key in a query parameter, which does the job of a URL token before the request reaches your code, and Hookdeck signs what it forwards, so your service can verify that the request came from Hookdeck. You can also manage the receiving side with the CLI, the API or the Terraform provider, even though the webhook itself is set up by hand.
Keep a WordPress.com delivery from disappearing when your endpoint is down.
Hookdeck Event Gateway accepts each WordPress.com delivery, queues it and retries to your service on your schedule, with a log of every attempt. WordPress.com signs nothing, so Event Gateway has no signature to verify, but it signs what it forwards so your service can verify those requests came from Hookdeck.