Aura Historia Partner Connect

By aurahistoria

0+ active installationsVersion 0.3.3

Connects WooCommerce to Aura Historia by creating and maintaining the product webhooks your store needs.

Description

Aura Historia Partner Connect connects a WooCommerce store to Aura Historia.

After you connect the store through Aura Historia OAuth, the plugin automatically:

  • creates and maintains exactly three WooCommerce product webhooks:
    • product.created
    • product.updated
    • product.deleted
  • keeps those managed webhooks in sync without creating duplicates
  • repairs plugin-owned webhooks after manual edits or deletion
  • generates and stores the WooCommerce webhook signing secret automatically
  • sends webhook deliveries to Aura Historia using the built-in endpoint pattern
  • pauses plugin-owned webhooks on deactivation
  • removes plugin-owned webhooks and plugin options on uninstall
  • queues the first published-product CREATE backfill once per ListingSource after successful configuration; failed setup/queueing leaves that first run pending for later retry, while ordinary repairs never start a fresh run
  • imports supported local shipping configuration and scoped item class/variation inputs through separate typed APIs after connection, local changes, periodic reconciliation and the Import shipping repair action

The plugin keeps the settings surface intentionally small. Merchants do not manually enter Aura Historia credentials in wp-admin. The OAuth flow sets and stores:

  • ListingSource ID (ls_ TypeID)
  • Aura Historia access token

Merchants do not enter:

  • a webhook delivery URL
  • a webhook secret

This plugin is intended for merchants who already use Aura Historia. Once OAuth completes, the plugin sends product data to Aura Historia so the connected catalog can stay in sync.

External services

This plugin connects to Aura Historia, a hosted service required for the plugin to work.

It sends data after a merchant connects the store through Aura Historia OAuth, and later when WooCommerce sends managed webhook events or the plugin runs a product backfill or shipping import. These background jobs run without an open admin page.

The service is used to:

  • register the generated WooCommerce webhook secret and current store locale details
  • receive ongoing product webhook deliveries
  • receive background product backfill batches
  • store typed shipping profiles, source defaults, listing selections and class/variation inputs acquired locally by the plugin

Data sent to the service may include:

  • when connecting, to the Aura Historia OAuth broker: the OAuth client ID, requested permissions, this store’s settings page URL, a random state value and a completion challenge, and later the transaction ID, the one-time completion code and the matching completion secret
  • ListingSource ID (ls_ TypeID)
  • Aura Historia access token in the bearer Authorization header for backend API calls
  • Aura Historia access token in a bearer Authorization header on managed live webhook deliveries
  • generated WooCommerce webhook secret
  • store language and currency
  • unchanged signed WooCommerce webhook payloads for product.created, product.updated, and product.deleted, including any WooCommerce descriptions
  • published products during backfill: WooCommerce product ID as sourceListingId, canonical URL, image URL array, optional localized title, optional tagged monetary price (exact integer currency minor units; non-representable prices omitted), and optional availability. Backfill does not send description/body yet (follow-up #93).
  • shipping import: supported geographic shipping rules and ordered zones, enabled service identifiers, exact/conditional rates and currency, pickup availability without addresses, source-scoped class/variation codes, WooCommerce product IDs, producer operation keys/order and actual acquisition time. Shipping requests do not contain credentials in their bodies, whole settings/metadata, customers, orders, addresses or full product descriptions.

Service endpoints:

  • POST https://aura-historia.com/api/oauth/client/redirect-broker/woocommerce/transactions (from the store’s server)
  • GET https://aura-historia.com/{language}/oauth/authorize (in the merchant’s browser)
  • POST https://aura-historia.com/api/oauth/client/redirect-broker/woocommerce/transactions/complete (from the store’s server)
  • PUT https://api.aura-historia.com/v1/listing-sources/{listingSourceId}/ingestion-configurations/woocommerce
  • POST https://api.aura-historia.com/v1/webhooks/woocommerce/{listingSourceId}
  • POST https://api.aura-historia.com/v1/listing-sources/{listingSourceId}/product-listings/async
  • GET/POST https://api.aura-historia.com/v1/listing-sources/{listingSourceId}/shipping-profiles
  • GET/PUT/DELETE https://api.aura-historia.com/v1/listing-sources/{listingSourceId}/shipping-profiles/{shippingProfileId} and POST .../{shippingProfileId}/restore
  • GET/PUT/DELETE https://api.aura-historia.com/v1/listing-sources/{listingSourceId}/shipping-default
  • GET/PATCH https://api.aura-historia.com/v1/listing-sources/{listingSourceId}/product-listings/by-source-id/{sourceListingId}/delivery

Service provider and policies:

Installation

  1. Install and activate WooCommerce.
  2. Install Aura Historia Partner Connect via the WordPress Plugin Directory.
  3. Activate the plugin.
  4. Go to WooCommerce > Aura Historia.
  5. Approve the Aura Historia OAuth connection when prompted. If the approval page does not open automatically, click Connect with Aura Historia.

The production public OAuth client ID is bundled; merchants do not need to configure it. For stage or local development, supply a separate registered canonical UUIDv7 oc_ client ID via AHPC_OAUTH_CLIENT_ID and the matching webapp origin via AHPC_OAUTH_BROKER_BASE_URL (constants or environment variables). Keep the API URL in that same environment. Configure the same client ID and its matching secret in the webapp OAuth broker and grant product-listings:read product-listings:write listing-sources:read listing-sources:write. Reconnect older connections to grant the read scopes shipping needs for identity/revision recovery. The broker must return an ls_ ListingSource ID in its completion response; UUID Shop IDs are rejected. The API uses https://api.aura-historia.com in production and https://api.stage.aura-historia.com for stage. The WordPress admin address must use HTTPS. After OAuth completes, the plugin configures WooCommerce ingestion and syncs the managed webhooks.

FAQ

Do I need an Aura Historia account?

Yes. This plugin is intended for merchants who already use Aura Historia and administer a ListingSource they can authorize during OAuth.

How does connecting keep credentials out of the browser?

The plugin registers each connection attempt with Aura Historia from your server and keeps a one-time secret on your server. Aura Historia returns your browser with an opaque completion code, and the plugin redeems that code together with the secret, server to server. The access token and ListingSource come only from that response; nothing the browser adds can change them. Each attempt can complete once, within 15 minutes, for the administrator who started it. Starting again replaces an unfinished attempt. A denied, expired or failed attempt leaves an existing connection unchanged; start again from the settings page.

Which WooCommerce events are sent?

Only product.created, product.updated, and product.deleted. The plugin’s own product.deleted webhook fires when a product is trashed and also when a product is deleted permanently, with or without Trash first. Deleting a single variation does not remove its parent product from Aura Historia. Your own WooCommerce webhooks keep their default behavior.

What data is sent to Aura Historia?

After configuration, the plugin sends the generated WooCommerce webhook secret, store language and currency, unchanged signed live product webhook payloads, published product listing data during backfill, and typed shipping rules and item inputs during shipping import. The backfill never sends description/body; live WooCommerce webhook bodies remain untouched. See External services above.

Can I change the delivery URL or webhook secret in wp-admin?

No. The plugin keeps the Aura Historia delivery URL built in and generates the WooCommerce webhook secret automatically.

What happens if I edit or delete one of the managed webhooks?

A background reconciliation repairs it shortly afterwards. Deleting a managed webhook triggers a sync, and so does any difference between its name, topic, status, delivery URL, secret, user or API version and what the plugin applies, including WooCommerce disabling it after repeated failed deliveries. Reactivation resets its failure count. WooCommerce’s own save after each delivery, which only records the failure count, does not trigger a sync. The plugin first stages all managed webhooks paused with the desired signing secret, then applies that secret, supported store currency, and language through the WooCommerce ingestion-configuration PUT. Only after it succeeds does sync activate the webhooks. Only one request synchronizes at a time, so simultaneous requests cannot create duplicate webhooks or activate a different connection, currency or language than the one registered. Reconnecting or changing WooCommerce currency or WordPress site language pauses delivery immediately until the new configuration is registered. Unsupported store currencies or configuration failures leave them paused for retry.

Does this plugin backfill existing products?

Yes. Once configuration succeeds, the plugin schedules an initial backfill once per canonical lowercase UUIDv7 ls_ ListingSource ID. If setup or queueing fails, it keeps that first run pending for a later healthy request. It submits published products in background batches of up to 100 to the async ProductListings API. A 202 confirms queue admission, not completed creation or immediate search visibility. Retries reuse the same ordered request and idempotency key; a product-ID cursor prevents skips when earlier products are removed. Routine webhook repairs never start a fresh CREATE run. The manual action safely resumes pending work without changing its snapshot/key, leaves already queued work alone, or starts a new full run only when idle, and its confirmation states which one happened. Overlapping background callbacks never submit the same page twice with different keys, and work started before a cancellation or reconnect cannot overwrite the current run. A batch that keeps failing with a timeout, HTTP 408, 429 or 5xx is retried after 1, 2, 4, 8, 16 and 32 minutes and then hourly, and after 10 failed attempts in a row every 6 hours until it is admitted, always with the same request and key.

What happens when Aura Historia is unreachable?

Storefront and other ordinary requests never contact Aura Historia, so an outage cannot slow them down. Webhook configuration is confirmed by a background Action Scheduler job, queued once per attempt. Timeouts, HTTP 408, 429 and 5xx responses are retried after 1, 2, 4, 8, 16 and 32 minutes and then hourly; after 10 failed attempts in a row, about four hours, the plugin keeps trying every 6 hours. Other errors, such as a revoked token, are shown as needing attention and are also retried every 6 hours. Retries never stop on their own, so delivery resumes without any action once Aura Historia is reachable again. Delivery stays paused until the configuration is confirmed. Sync webhooks now, reconnecting, changing the store currency or site language, reactivating or updating the plugin try again at once.

What happens when the plugin is disabled?

Plugin-owned webhooks are paused on deactivation so WooCommerce stops sending deliveries. Queued webhook reconciliation and backfill work is stopped. Reactivation reconciles the webhooks again, while a stopped backfill keeps its pending batch for the manual resume action. Shipping jobs are fenced/canceled, and the plugin attempts protected retirement of its shared shipping profile and clearing of its source default. This is not source authorization revocation. Unconfirmed cleanup is visible after reactivation; review retained assertions in Aura Historia. Existing assertions have no automatic expiry.

Which shipping settings are supported?

Ordered zones including fallback zone 0, country restrictions, reviewed state codes, exact postcodes and reviewed German postcode forms, core constant/quantity flat rates, bounded per-class quantity charges, conditional free shipping and conservative local pickup. Shared base/class surcharges, per-order class maxima, coupon/tax/cart context, unreviewed geography, third-party methods and other expressions remain uncertain or externally calculated. Nothing runs checkout or evaluates arbitrary expressions. Zones without locations retain their position and cover the permitted shipping countries. Class charges are ignored when no shipping classes exist, matching WooCommerce. The complete support matrix is in the repository README.

How do shipping imports recover?

Import shipping resumes immutable pending work and retries missing catalog listings without recreating products. Each background action makes at most one write; automatic retries and retained deferred work are bounded. Progress, manual protection and capability limits appear on the settings page. Shipping policy is shared in profiles, while item inputs remain separate. Incomplete reads preserve previous assertions; only confirmed local removals or complete scoped replacement remove owned assertions. Manual edits remain protected. A restored product cancels unsent removals and refreshes its selection and inputs. When Trash has already withdrawn a product’s Aura Historia listing, Aura refuses to clear its shipping. The plugin does not report that removal as done and does not retry it periodically. It continues with other products, never restores the listing, and counts these products on the settings page. Restoring the product publishes its current shipping again.

Local hooks observe zone/location/order changes (including fallback zone 0), method addition/deletion/enablement and instance settings, shipping classes, core settings/units/currency, product inputs and variation inheritance. Save requests only mark durable identities. Background workers reread current facts and reuse the initial/manual publisher. Missed changes converge through six-hour reconciliation with bounded product traversal and pages of 20 previously published identities. Unsupported plugin behavior remains conservative; failed or incomplete reads never establish removal. No shipping refresh recreates catalog products.

WooCommerce Action Scheduler and a working WordPress cron or server runner are required. Low-traffic sites or DISABLE_WP_CRON installations need a server cron trigger or an Action Scheduler CLI runner, for example wp action-scheduler run --group=aura-historia-shipping. No browser session is required. The settings page shows oldest pending/failed work, deferred components, protected edits and last confirmed API write. Search indexing completes separately. Automatic attempts stop after five failures; up to 100 deferred components are retained before stopping at a checkpoint. Repeated refreshes reuse the entry of a component that is already deferred, such as an unsupported product type, and send no new request for a component until its retained request is resolved. Periodic/manual refreshes resume retained work.

Shipping assertions remain valid until updated, withdrawn or their source loses authority, without expiry or keepalive, including after 30 days. Reconnect/reactivation requires a fresh local acquisition; old jobs cannot relabel/replay their captures into a new connection. Valid Aura token rotation preserves immutable retries and uses the current token at execution. Deactivation/reconnect/uninstall attempt existing protected cleanup where possible and record whether it committed. Cleanup preserves manual terms and does not revoke authorization. Uninstall removes local shipping jobs/state and records a bounded diagnostic if remote cleanup was not confirmed. Lost credentials or unreachable Aura can leave assertions eligible until explicitly changed in Aura.

No WooCommerce REST key/secret is needed or exported; the backend never calls the plugin. Scheduled action arguments, status and diagnostics exclude credentials, raw settings and pending request contents. The three signed product webhook bodies and their receiver remain unchanged. The repository README documents hook and supported-version coverage.

Rescheduling a published product for future publication clears its owned shipping components until it is published again. A failed local removal recheck retains the original request and bounded retries; only confirmed restoration cancels a pending removal.

Changelog

0.3.3

  • Stops the managed product.deleted webhook from reporting permanently deleted variations. WooCommerce 11.3 and later also send that topic for them, including every variation removed with its variable parent; variations have no listing of their own, so only the parent product’s deletion is sent. Your own WooCommerce webhooks keep their default behavior.

0.3.2

  • Connects through version 2 of the Aura Historia OAuth broker protocol. The browser no longer carries a PKCE verifier or readable broker state, the token and ListingSource come from one proof-protected server-to-server response, and replayed, tampered or stale callbacks are rejected. Requires AHPC_OAUTH_BROKER_BASE_URL instead of AHPC_OAUTH_BROKER_REDIRECT_URI for non-production environments; the previous handshake is no longer supported.
  • Moves automatic webhook reconciliation into background jobs, so Aura Historia outages no longer delay storefront or other ordinary requests.
  • Retries webhook configuration and retryable product backfill failures with increasing delays, continuing every six hours after ten failed attempts. The settings page shows pending work, scheduled retries, failures needing attention and stopped backfills.
  • Coordinates concurrent backfill workers to prevent duplicate page submissions and stale callbacks overwriting newer runs. Retried batches keep the same product snapshot and idempotency key, including after reconnecting the same ListingSource.
  • Serializes webhook synchronization and activates delivery only for the connection and store context confirmed by Aura Historia. Connection, currency and language changes pause delivery until the matching configuration succeeds.
  • Stops queued webhook reconciliation and backfill work on deactivation and prevents running jobs from reactivating delivery or overwriting stopped work. The manual backfill action resumes retained batches safely.
  • Preserves pending backfill data when credentials are missing, reports failed catalog reads and retries malformed batch admission responses. Detects failed webhook saves and tightens managed-webhook recovery and input validation.

0.3.1

  • Withdraws the Aura Historia listing when a product is permanently deleted, including forced REST/CRUD deletes, Empty Trash, the scheduled Trash purge and sites with Trash disabled.
  • Repairs the managed webhooks only on real drift. Routine WooCommerce delivery bookkeeping no longer pauses and re-syncs all three webhooks, and reactivating an auto-disabled webhook resets its failure count.
  • A removal refused because Trash already withdrew the listing no longer stalls shipping. Other products continue, the listing is never restored, and the settings page counts the affected products.
  • Keeps one deferred entry per unresolved shipping component, so periodic refreshes no longer fill the deferred limit with duplicates. Duplicates left by 0.3.0 are compacted.
  • Fixes the automatic OAuth start on the first settings page visit (form.submit is not a function).
  • The manual product backfill now states whether it started a fresh run, resumed interrupted work or left already queued work unchanged.
  • Opening a new product editor no longer queues failing shipping work for its auto-draft.
  • Starts WooCommerce integration at init, so early webhook synchronization no longer emits translation notices that break redirects.

0.3.0

  • Bundles the production OAuth client ID and uses the production /v1 API contract.
  • The plugin now auto-configures with Aura Historia on installation. No more manual insertion of credentials needed. Just install, activate, and approve the OAuth connection when prompted.
  • Adds background initial/manual shipping imports with conservative local mapping, resumable retries and protection for manual Aura edits.
  • Refreshes shipping after local changes and bounded periodic reconciliation, with durable retry scopes, connection fencing and recorded lifecycle cleanup.

0.1.0

  • Initial release.