Reference

Webhook Reference

Every Shopify webhook OrderWise registers, what it does with each payload, and how to debug delivery failures.

Last updated

OrderWise subscribes to twelve Shopify webhooks across orders, fulfillments, customers, returns, refunds, products, inventory, and the mandatory GDPR endpoints. Every webhook is HMAC-verified at the request boundary; payloads that fail verification are dropped without further processing.

Order events

  • orders/create — registers a new order in OrderWise's conversation context so subsequent customer questions can resolve to it. Triggers a webhook event for any active execution rule subscribed to "order_created".
  • orders/updated — keeps the cached order metadata in sync with Shopify. Most commonly fires on financial-status changes and address edits.
  • orders/cancelled — marks the order as cancelled in OrderWise so the AI doesn't continue treating it as active.

Fulfillment events

  • fulfillments/create — populates tracking info into the order context. Triggers any "shipped" auto-rule.
  • fulfillments/update — keeps tracking state current. Most carriers fire this on every scan.

Returns and refunds

  • returns/request — surfaces customer-initiated returns. Triggers auto-rules for return approval.
  • returns/approve — confirms a return that was either auto-approved or merchant-approved.
  • refunds/create — keeps the refund ledger in sync. Used by the monthly-report generator.

Customer events

  • customers/data_request — GDPR Art. 15. Generates the export payload and emails the merchant.
  • customers/redact — GDPR Art. 17. Anonymizes all conversation records for the customer.
  • shop/redact — fires 48 hours after app uninstall. Triggers a full purge of the shop's OrderWise data.

Metaobjects (optional)

  • metaobjects/create, metaobjects/update, metaobjects/delete — fires when the merchant edits an orderwise_faq entry inside Shopify. OrderWise resyncs the knowledge base index.

Debugging delivery

Webhook delivery logs are visible in two places:

  • The merchant's Shopify admin under Settings → Notifications → Webhooks shows Shopify's view of delivery (success / retry queue).
  • OrderWise's Settings → Diagnostics tab shows the receiving side: the most recent successful delivery per topic, the most recent failure, and the verification status (HMAC OK / mismatch).

If the Shopify side shows success but OrderWise's side shows "not received," the most common cause is an HMAC verification failure — the shop's secret has been rotated and OrderWise hasn't picked it up. Re-authorize the app to refresh the secret.