Shopify Order Webhook

The Shopify Order Webhook is how a completed Shopify order becomes a SimplyClub loyalty event. When a customer checks out, Shopify sends an event to SimplyClub's server. SimplyClub uses that event to finalize the transaction — award points, lock in the chosen benefit, and (on refunds) reverse the loyalty impact.

Without this webhook, your store would still show benefits in the cart, but nothing would be recorded on the SimplyClub side after checkout.

What the webhook does

Endpoint

POST https://<simplyclub-server>/v1/transaction/shopify-webhook
Content-Type: application/json

Shopify must be configured to deliver the topics above to this URL.

How an order is linked to SimplyClub

Each order must carry a sc_transaction_code in its note_attributes. This is the key that links the Shopify order back to the SimplyClub session that produced its benefit.

If you installed via the SimplyClub Theme App Block (see Install on Shopify), this is wired automatically — the block stores sc_transaction_code on the cart as soon as the SimplyClub drop-in issues a transaction code, and Shopify carries cart attributes into the order's note_attributes.

If you're sending webhooks from a custom integration, the order body must contain:

{
  "id": 5001,
  "order_number": 1042,
  "customer": { "id": 9001 },
  "note_attributes": [
    { "name": "sc_transaction_code", "value": "TXN_abc123" }
  ]
}

Required headers

Where to get the webhook secret

The webhook secret is what makes Shopify's signature verifiable on the SimplyClub side. How you obtain it depends on which path you used to install:

If you use the SimplyClub Shopify App (recommended)

You do not need to set the secret yourself. When you install the SimplyClub app from the Shopify App Store, it registers webhooks for your store and SimplyClub manages the secret end to end. Skip to Verify the webhook is firing.

If you're registering webhooks from a custom or partner-built Shopify app

You need to coordinate one shared secret between the Shopify side and the SimplyClub side.

Step 1 — Get a secret value. Either:

• Generate one (a 64-character hex string is recommended), or
• Request one from SimplyClub support so it's registered on SimplyClub's side first.

Step 2 — Configure it in Shopify. Open the right place depending on your app type:

Paste the secret and save. From this point on Shopify will sign every outgoing webhook with this key and include x-shopify-hmac-sha256 in the headers.

Step 3 — Register the same secret with SimplyClub. Send the secret to SimplyClub support so it can be stored against your merchant account, or use the vendor admin tools you've been given access to. The signature can only be verified once both sides agree on the same secret.

Important: Treat this secret like a password. Don't commit it to source control, don't expose it in client-side code, and don't paste it into logs. If you suspect it has leaked, rotate it on both sides simultaneously.

Configure webhook topics in Shopify

Whichever path you used, the webhook needs at least these topics pointed at the SimplyClub endpoint:

• orders/paid — required for points to accrue
• refunds/create — required if you want refunds to reverse points (and you have toggled the topic on in the SimplyClub dashboard for this POI)

In a Custom App, register topics under Settings → Notifications → Webhooks. In a Partner App, register them via the Admin API or the app's webhook configuration screen.

Per-POI topic toggles

Even with the webhook registered, SimplyClub will only act on topics that are enabled for your POI. You can toggle topics from the SimplyClub dashboard. Defaults:

• orders/paid — on
• refunds/create — off

Turning a topic off means SimplyClub will accept the webhook and return 200, but take no action.

Verify the webhook is firing

Place a test order in your store, then check the SimplyClub dashboard logs for an entry like:

💰 WEBHOOK RECEIVED | Topic: orders/paid | Order ID: <id> | Transaction Code: TXN_… | Domain: <yourshop>
✅ POI found
🔄 Processing webhook topic: orders/paid
💰 WEBHOOK COMPLETED | … | <ms>ms

If you don't see a log entry at all, the webhook isn't reaching SimplyClub — check the Shopify webhook delivery history for delivery attempts and error responses.

Common rejection reasons

Related

• Install on Shopify — how to add the SimplyClub block and where sc_transaction_code is set.
• Membership CTA Web Component — for embedding the join/upgrade CTA outside the main drop-in.