WooCommerce Webhook MCP Server

WooCommerce Webhook

WooCommerce REST webhooks POST a JSON body with Content-Type: application/json. The payload mirrors the WooCommerce REST API resource for the subscribed topic — orders, customers, products, coupons, or custom action hooks. Each delivery is one POST stored as parsed JSON in export.json. Tools read what already landed; there is no pull API and no way to update orders, replay webhooks, or change store state from here.

Upstream also sends topic headers (X-WC-Webhook-Topic, X-WC-Webhook-Resource, X-WC-Webhook-Event, X-WC-Webhook-Delivery-ID) on the HTTP request; the stored export.json is the resource body only — infer topic from payload shape when headers are not in storage.

First moves

1. Latest report — default for “what order or event arrived last”.
2. Classify the payload — order objects have line_items and status; customers have email without line items; products have sku / type.
3. Recent reports — compare id, status, and date_modified when deduping retries or rapid updates.
4. One report by id — after listing, when the user names a specific delivery.

Webhook topics (typical)

Configured per webhook in WooCommerce admin or REST API:

Order fields (export.json)

Order webhooks carry the full order object. Read these first:

Identity and status

• id — WooCommerce order id (primary dedupe key)
• parent_id — parent order when this is a refund or subscription child
• status — e.g. pending, processing, on-hold, completed, cancelled, refunded, failed
• number — human-facing order number (may differ from id)
• currency, prices_include_tax, customer_id, customer_note

Timestamps

• date_created, date_modified, date_completed, date_paid — ISO8601 strings from the store

Totals

• discount_total, shipping_total, total, total_tax
• payment_method, payment_method_title, transaction_id

Billing (billing object)

• first_name, last_name, company
• address_1, address_2, city, state, postcode, country
• email, phone

Shipping (shipping object) — same address keys as billing when a physical shipment applies.

Line items (line_items[])

• id, name, product_id, variation_id, quantity
• sku, price, subtotal, total, total_tax
• meta_data — per-line custom fields

Other common blocks

• shipping_lines[], fee_lines[], coupon_lines[], refunds[]
• meta_data[] — store-specific custom order fields (key, value)

Customer fields (export.json)

• id, email, first_name, last_name, username
• billing, shipping — same shape as order addresses
• meta_data — custom customer fields

Product fields (export.json)

• id, name, slug, type (simple, variable, grouped, external)
• status, sku, price, regular_price, sale_price
• stock_status, stock_quantity, manage_stock
• categories[], tags[], images[], attributes[], variations[]

Response shape

• export.json — parsed webhook JSON (preferred for order, buyer, and line-item questions).
• export.text — raw body when JSON is large or non-object.
• source.captured_at — when the POST landed here; compare to date_modified inside JSON for upstream timing.

Operational order

1. Start with the latest report — do not guess a report id.
2. Read id and status (orders) or email (customers) before quoting amounts or buyer details.
3. If captured_at is older than expected, say so — webhooks fire when store events happen upstream.
4. List recent reports only for history, duplicate suspicion, or explicit compare-by-date asks.
5. Read ## This connection in the skill supplement for store-specific meta keys or status workflows.

Gotchas

• Read-only — cannot fulfill, refund, cancel, or replay WooCommerce webhooks from here.
• Payload mirrors REST API — field names and nesting match WooCommerce REST docs; extensions may add meta_data keys.
• Retries and duplicates — failed deliveries retry; the same order can produce multiple order.updated POSTs with the same id but newer date_modified. Dedupe on id + date_modified + status, not id alone.
• Topic not in JSON — when the user asks “was this a create or update?”, infer from context or list recent deliveries; stored body alone may not include X-WC-Webhook-Topic.
• Variable presence — shipping, line_items, refunds, and subscription fields appear only for relevant orders; guest checkout may leave customer_id as 0.
• Action topics — custom action.* webhooks may POST non-order JSON; do not assume every delivery is an order.