Extension and platform handoffs

Before sending platform handoffs

Use this page when a browser extension, WordPress/WooCommerce plugin, Shopify app or Shopify compliance webhook sends customer-approved evidence into WebRiskOps. These endpoints accept scoped diagnostics and provider events; they do not collect credentials, order records, payment data or full private site exports.

• Use placeholder values only; never paste real API keys, webhook secrets, tokens or customer data into documentation examples.
• Use `Authorization: Bearer ${WEBRISKOPS_PLATFORM_TOKEN}` only for the extension, CMS plugin and Shopify diagnostic upload routes.
• Use Shopify HMAC headers for `POST /api/shopify-app/webhooks/compliance`; do not substitute a bearer token for provider webhook verification.

Choose the platform handoff route

Follow the path `Authentication and headers → Platform add-on → Handoff route → Safe payload → Accepted evidence or blocked state`.

1. Open Authentication and headers and choose the platform add-on you are wiring. Result: the request uses the expected bearer token ability or Shopify signature model before any diagnostics leave the customer environment.
2. For browser extension evidence, send `POST /api/browser-extension/evidence-captures` with route name `browser-extension.evidence-captures.store` and token ability `browser-extension:evidence-upload`. Result: WebRiskOps can store active-tab evidence only for a project or report the token user can manage.
3. For WordPress and WooCommerce diagnostics, send `POST /api/cms-plugins/wordpress-woocommerce/diagnostics` with route name `cms-plugins.wordpress-woocommerce.diagnostics.store` and token ability `cms-plugin:diagnostics-upload`. Result: plugin diagnostics stay limited to the approved WordPress/WooCommerce project.
4. For Shopify app diagnostics, send `POST /api/shopify-app/diagnostics` with route name `shopify-app.diagnostics.store` and token ability `shopify-app:diagnostics-upload`. Result: Shopify storefront and theme diagnostics are accepted only when granted_scopes stay inside the safe read scope list.
5. For Shopify compliance webhooks, send `POST /api/shopify-app/webhooks/compliance` with route name `shopify-app.webhooks.compliance`, `X-Shopify-Hmac-Sha256`, `X-Shopify-Topic` and `X-Shopify-Shop-Domain`. Result: only signed `customers/data_request`, `customers/redact` and `shop/redact` topics reach the compliance handler.
6. Include `project_id` on every diagnostic upload and include `report_id` only when the evidence belongs to an existing report. Result: WebRiskOps rejects report_id values that do not belong to the selected project.
7. Keep retry logs tied to an `Idempotency-Key` value when your client framework retries the same upload. Result: developers can trace duplicate client attempts without placing secrets or payload hashes in the request body.
8. Send only safe diagnostic fields and artifact references. Result: page evidence, plugin status and Shopify storefront signals can route automatically without customer orders, payment details, cookies, passwords or raw private site exports.
9. Treat `201 Created` diagnostic responses and `204 No Content` Shopify compliance responses as accepted. Result: the caller can stop retrying and link the accepted handoff to the project or report.
10. Continue to the platform-specific documentation or Errors, idempotency, retries and rate limits when a request returns 401, 403, 422 or 503. Result: blocked auth, ability, validation and provider-secret states have a concrete next action.

Configure evidence and diagnostics payloads

Each route accepts a narrow payload for automated routing.

• Browser extension captures include `project_id`, optional `report_id`, `page_url`, optional `page_title`, `selected_text`, `meta_description`, `canonical_url`, `heading_outline`, `captured_at` and `extension_version`.
• WordPress and WooCommerce diagnostics include `platform: wordpress_woocommerce`, `site_url`, optional `plugin_version` and `diagnostics.wordpress_version`, `diagnostics.woocommerce_version`, `diagnostics.active_theme`, `diagnostics.active_plugin_names`, `diagnostics.checkout_page_url`, `diagnostics.woocommerce_status` and `diagnostics.visible_browser_symptoms`.
• Shopify app diagnostics include `shop_domain`, optional `shop_name`, `granted_scopes`, optional `app_version` and `diagnostics.primary_domain`, `diagnostics.published_theme_name`, `diagnostics.theme_count`, `diagnostics.product_count_bucket`, `diagnostics.checkout_profile_status`, `diagnostics.app_embed_status` and `diagnostics.visible_storefront_symptoms`.
• Shopify diagnostic `granted_scopes` must be one or more of `read_content`, `read_products` and `read_themes`.
• Shopify compliance webhooks validate the raw body with `X-Shopify-Hmac-Sha256` and read the topic and shop domain from `X-Shopify-Topic` and `X-Shopify-Shop-Domain`.
• JSON validation rejects unsupported platform keys, unsafe Shopify scopes, malformed URLs, invalid shop domains and report/project mismatches before a handoff record is stored.

Ready extension and platform handoff states

Continue only when the handoff can be accepted without broad access or private data.

• Extension token ready means the bearer token has `browser-extension:evidence-upload` and the selected user can manage the project or report.
• CMS token ready means the bearer token has `cms-plugin:diagnostics-upload` and the payload platform is wordpress_woocommerce.
• Shopify diagnostic token ready means the bearer token has `shopify-app:diagnostics-upload` and granted_scopes contains only safe read scopes.
• Shopify compliance signature ready means `X-Shopify-Hmac-Sha256` matches the raw body and the configured Shopify webhook secret.
• Project/report match ready means report_id belongs to project_id before evidence is attached.
• Safe payload ready means the upload contains route-specific diagnostics without cookies, payment fields, customer orders, passwords, API keys or raw private exports.

Blocked extension and platform handoff states

Blocked states should show which credential, scope or payload field to fix.

• `UNAUTHORIZED` means the bearer token is missing or the Shopify webhook signature is invalid.
• `FORBIDDEN` means the Sanctum token exists but does not have the required upload ability.
• `SIGNATURE_INVALID` means the Shopify HMAC calculation or shared webhook secret does not match the raw request body.
• `VALIDATION_FAILED` means required fields such as project_id, page_url, platform, site_url, shop_domain, granted_scopes, topic or shop domain headers are missing or malformed.
• `422 Validation failed` can also mean report_id does not belong to the selected project or Shopify topic is not one of the mandatory compliance topics.
• `503 Service unavailable` means the Shopify webhook secret is not configured, so compliance webhooks must fail closed until configuration is fixed.
• Any payload containing credentials, customer order records, payment details, cookies, local storage, full HTML exports or private database content should be rejected before retrying.

Continue after platform handoff

After a handoff is accepted, continue to Browser extension evidence capture, WordPress and WooCommerce diagnostics or Shopify diagnostics for the customer-facing workflow. Use Request and response examples for placeholder JSON, Authentication and headers for token or HMAC setup, and Errors, idempotency, retries and rate limits when the caller needs to interpret 401, 403, 422 or 503 responses.