# 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](https://wordpress.org/plugins/wp-webhooks/). [WooCommerce](/webhooks/woocommerce) has its own signed webhooks.

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

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [WordPress.com's official docs](https://wordpress.com/support/webhooks/).

[Overview](https://hookdeck.com/webhooks/wordpress-com) · [Webhook events (3)](https://hookdeck.com/webhooks/wordpress-com/events) · [MCP events](https://hookdeck.com/webhooks/wordpress-com/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/wordpress-com/verify) · [Production guide](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/wordpress-com/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `None (unsigned)` | [WordPress.com docs](https://wordpress.com/support/webhooks/) |
| How events are identified | `hook field in the body` | [WordPress.com docs](https://wordpress.com/support/webhooks/) |
| Envelope | `hook` | [WordPress.com docs](https://wordpress.com/support/webhooks/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill wordpress-com-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/wordpress-com/skill) |
| Not yet known | body format | [Help fill this in](https://hookdeck.com/contact) |

[Verify WordPress.com webhooks](https://hookdeck.com/webhooks/wordpress-com/verify)

## 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](https://developer.wordpress.com/docs/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](https://wordpress.com/blog/2010/04/14/hook-line-and-sinker/), whose sender form-encodes the fields, so expect form data and capture one delivery to confirm it.

## 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](https://inspect.hookdeck.com) 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

- **Timeout:** not documented. WordPress.com's docs give no limit, so respond quickly. [Guide](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#timeouts)
- **Retries:** not documented. no retry behaviour or resend control is described. [Guide](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#retries)
- **After a failure:** not documented. no delivery log or failure alert is described. [Guide](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#retries)
- **Duplicates:** edits fire again. `publish_post` and `publish_page` also run when a published item is edited. [Guide](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#duplicates)

## Known failure modes

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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#other-limits)
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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#duplicates)
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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#testing)

From [Hookdeck's WordPress.com guide](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts).

## WordPress.com webhook best practices

- **[Protect the URL yourself](https://hookdeck.com/webhooks/wordpress-com/verify).** 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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#duplicates).** `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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#choosing-events).** 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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts#choosing-events).** `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](https://hookdeck.com/webhooks/wordpress-com/events#publish_post): Post is published, or edited while published
- [publish_page](https://hookdeck.com/webhooks/wordpress-com/events#publish_page): Page is published, or edited while published

### Comments

- [comment_post](https://hookdeck.com/webhooks/wordpress-com/events#comment_post): Comment is saved to the site's database

## Events

| Resource | Events | Payloads |
|---|---|---|
| [WordPress.com events](https://hookdeck.com/webhooks/wordpress-com/events#resource-other) | 3 | 0 |

[All 3 events](https://hookdeck.com/webhooks/wordpress-com/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/wordpress-com/events): Every covered WordPress.com event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/wordpress-com/mcp-events): How an agent subscribes to WordPress.com events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/wordpress-com/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/wordpress-com/guide-duplicates-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/wordpress-com/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill wordpress-com-webhooks`
---

Not affiliated with WordPress.com. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/wordpress-com.json) · [Report a correction](https://hookdeck.com/contact)
