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.

3 events covered

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

Signature header
None (unsigned)
How events are identified
hook field in the body
Agent skill
npx skills add hookdeck/webhook-skills --skill wordpress-com-webhooks
Not yet known

Body format

Not in the registry yet.

Verify WordPress.com webhooks →

Setting up WordPress.com webhooks

  • Add /wp-admin/options-general.php?page=webhooks to 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_email and comment_author_IP are 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

  1. 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 →
  2. An edit looks like a new publish

    publish_post and publish_page also run each time a published item is edited, and no delivery ID is documented. Key on hook, ID and post_modified_gmt, which you have to select on the webhook.

    Handle repeat deliveries →
  3. 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 →
  4. 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_post and publish_page also fire when a published item is edited. Select ID and post_modified_gmt, then key on those two and hook.
  • 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_after on the posts endpoint and after on the comments endpoint to fetch what you missed.
  • Check comments before you show them. comment_post runs when a comment is saved, which can be before it's approved. Select comment_approved and 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

comment_post · publish_page · publish_post

3 0

All 3 events →

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.

Not affiliated with WordPress.com. Facts are compiled from public sources and linked inline.