Single-Click App Callback Handlers

After a store owner or authorized user installs your single-click app, they and other authorized users will need to use it and configure any settings. In turn, your app will likely need to store and manage information about the stores and users you’re supporting.

This article is a reference for endpoints to which we send event-driven callbacks, and a guide to writing handlers that verify and use our JWT payloads. It also describes the payload schema of the signed_payload_jwt.

Overview

Your app’s front-end views render inside an iFrame in the store control panel, so your app has no native ability to listen for a few high-level events. To support your work, BigCommerce sends GET requests to callback routes in your app that correspond to three events: opening the app, uninstalling the app, and revoking a user’s access to the app. Each request includes a signed JSON web token (JWT), which contains identifying information about the store and the user.

Your app is only required to handle the GET /auth and GET /load endpoints, but we recommend writing handlers for the others, as well. Please see the corresponding detail sections that follow for more about the consequences of not handling optional callback endpoints.

The following table lists the app management callbacks that BigCommerce stores send: the three listed in the preceding paragraph, plus the auth callback described in Single-Click App OAuth Flow.

Render the app with load

Once the store owner or authorized user installs your app, it appears on the Apps sub-menu list in their store control panel, as well as their authorized users’ control panels. When a user clicks your app’s listing or another referring UI component, BigCommerce dispatches a request to your app’s GET /load endpoint. The following is an example request:

GET https://your_app.example.com/load?signed_payload_jwt={header_b64.payload_claims_b64.signature_b64}
Accept: application/json

After your app verifies the payload, identifies the requesting user, and handles any internal business, respond with the markup and assets for the view that you want BigCommerce to render in the provided iFrame.

Deactivate stores with uninstall

When the store owner or authorized user clicks the Uninstall button on your app’s card in the store control panel, BigCommerce dispatches a request to the app’s GET /uninstall endpoint. The following is an example request:

GET https://your_app.example.com/uninstall?signed_payload_jwt={header_b64.payload_claims_b64.signature_b64}
Accept: application/json

After your app verifies the payload and identifies the requesting user, handle any internal business, such as marking the user inactive in your app’s database or decrementing the number of active installations. You do not need to send a response. If you do not write a handler for the GET /uninstall endpoint, BigCommerce will still uninstall your app from the owner’s store, but your app will not know that.

Revoke user access with remove_user

When the store owner revokes a user’s authorization to access your app, BigCommerce dispatches a request to the app’s the GET /remove_user endpoint. The following is an example request:

GET https://your_app.example.com/remove_user?signed_payload_jwt={header_b64.payload_claims_b64.signature_b64}
Accept: application/json

After your app verifies the payload and identifies the requesting user, handle any internal business, such as removing the user’s data from your app database. You do not need to send a response. If you do not write a handler for the GET /remove_user endpoint, BigCommerce will still revoke the user’s access to your app in the store control panel, but your app will not know that.

Decode and verify signed_payload_jwt

The signed_payload_jwt is composed of three distinct base64URL-encoded strings concatenated with the . character.

header_b64.payload_claims_b64.signature_b64

Use a compatible BigCommerce API client or a standard library package (jwt.io) to decode, verify, and parse the signed_payload_jwts that BigCommerce sends to your app’s callback endpoints.

Work with payload claims

Use the payload claim data to identify the store and user. What your app should do with this information typically depends on whether it supports multiple users. Refer to the following table for instructions:

The following is an example of the payload claims encoded in the signed_payload_jwt that BigCommerce sends to your app callback endpoints:

{
  "aud": "U8RphZeDjQc4kLVSzNjePo0CMjq7yOg", // your app's CLIENT_ID
  "iss": "bc",
  "iat": 1659031626,
  "nbf": 1659031621,
  "exp": 1659118026,
  "jti": "c5f0bcf5-a504-4ae6-8dcc-0e40eaa5a070", // JWT unique identifier
  "sub": "stores/z4zn3wo", // STORE_HASH
  "user": {
    "id": 9876543,
    "email": "authorized_user@example.com",
    "locale": "en-US"
  },
  "owner": {
    "id": 7654321,
    "email": "owner@example.com"
  },
  "url": "/",
  "channel_id": null
}

Data properties in the signed_payload_jwt

Helpful tools

The following BigCommerce API clients expose helper methods for verifying the signed_payload_jwt:

• Python API client
  • Fetches access_token
  • Verifies signed_payload_jwt
• Node API client
  • Fetches access_token
  • Verifies signed_payload_jwt

Next step

• Support multiple users

Resources

Sample apps

• Node / React / Next.js with quick start tutorial
• Python / Flask
• PHP / Silex
• Ruby / Sinatra
• Laravel / React

Tools

• Node API Client
• Python API Client
• PHP API Client
• Ruby API Client
• Ruby OmniAuth Gem
• BigDesign Developer Playground
• Figma Component Library

Blog posts

• How to Test App Authentication Locally with ngrok
• Building a BigCommerce App Using Laravel and React
• BigDesign Tutorial