WordPress.com webhooks
WordPress.com webhooks are HTTP POST requests a WordPress.com site sends to a URL you set when a post or page is published or edited, or a comment is saved.
These pages cover the built-in webhooks on WordPress.com sites. They don't apply to plugin-enabled sites or to self-hosted WordPress, which needs a plugin such as WP Webhooks. WooCommerce has its own signed webhooks.
How WordPress.com webhooks work
Webhooks push a site's posts, pages and comments to your app as they change, so you don't have to keep polling the REST API. Each webhook has one action, the fields you chose for it and a URL. When the action fires, WordPress.com sends an HTTP POST to that URL.
The post data holds the fields you selected plus hook, which names the action, so hook is the one field every delivery has. WordPress.com doesn't name a content type, publish an example body or document a version. It built the feature from the HookPress plugin, whose sender form-encodes the fields, so expect form data and capture one delivery to confirm it.
Key facts
Setting up WordPress.com webhooks
- Add
/wp-admin/options-general.php?page=webhooksto your site's URL, click Add webhook, then choose an action, its fields and a URL. Only admin-level users can add or manage webhooks, and each webhook's row lets you edit, delete, activate or deactivate it. - Select only the fields you need, including an ID to key on.
post_password,comment_author_emailandcomment_author_IPare all selectable, and selecting them sends them to your URL. - To test, trigger a real action by publishing a post or page or submitting a comment, because WordPress.com's docs describe no test button. Point the webhook at a public URL, such as Hookdeck Inspect or a tunnel, to see what arrives.
- WordPress.com's docs describe no way to resend a delivery. Recover missed events from the REST API.
Delivery behaviour
not documented WordPress.com's docs give no limit, so respond quickly Retries not documented no retry behaviour or resend control is described After a failure not documented no delivery log or failure alert is described Duplicates edits fire again publish_post and publish_page also run when a published item is edited Known failure modes
From Hookdeck's WordPress.com guide →-
Anyone with the URL can send a fake delivery
WordPress.com doesn't sign its webhooks, and its docs describe no secret or auth setting, so your endpoint can't prove a delivery came from WordPress.com. Put a long random token in the URL, use HTTPS, and re-fetch from the REST API before doing anything that matters.
Protect the endpoint → -
An edit looks like a new publish
Handle repeat deliveries →publish_postandpublish_pagealso run each time a published item is edited, and no delivery ID is documented. Key onhook,IDandpost_modified_gmt, which you have to select on the webhook. -
A failed delivery may be lost
WordPress.com's docs describe no retries, delivery log or resend, so plan as if a delivery your endpoint misses won't come back. Fetch what changed from the REST API on a schedule.
Recover missed events → -
The body format isn't documented
WordPress.com doesn't name a content type or show an example body. HookPress, the plugin it was built from, sends form data, so a handler that only parses JSON may see an empty body. Capture one delivery and check.
Capture a delivery →
WordPress.com webhook best practices
- Protect the URL yourself. WordPress.com signs nothing, so anyone who finds the URL can post to it. Add a long random token to the URL, use HTTPS, and compare the token on every request.
- Respond quickly. WordPress.com's docs don't give a timeout or say whether a slow response affects the publish. Return a 2xx first and do the work in a background job.
- Treat edits as repeat deliveries.
publish_postandpublish_pagealso fire when a published item is edited. SelectIDandpost_modified_gmt, then key on those two andhook. - Read every field defensively.
Only the fields selected for the webhook are sent, so one can go missing after someone edits the webhook. Dispatch on
hook, the one field that's always there. - Run reconciliation jobs.
WordPress.com documents no retries, so a failed delivery may never come back. Use
modified_afteron the posts endpoint andafteron the comments endpoint to fetch what you missed. - Check comments before you show them.
comment_postruns when a comment is saved, which can be before it's approved. Selectcomment_approvedand check it.
Common WordPress.com webhook events
Posts and pages
publish_post | Post is published, or edited while published |
publish_page | Page is published, or edited while published |
Comments
comment_post | Comment is saved to the site's database |
Events
| Resource | Events | Payloads |
|---|---|---|
WordPress.com events | 3 | 0 |
In this hub
| Webhook events → | Every covered WordPress.com event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to WordPress.com 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 wordpress-com-webhooks |
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.