IntegrationsAppsGuide

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.

Callback URL requirements

In production, all app callback URLs must be publicly available, fully qualified, and served over TLS/SSL.

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{:http} and GET /load{:http} 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.

EndpointRequiredRequest OriginPayloadExpected ResponseEvent Description
GET /auth{:http}yesbrowserURL-encodedmarkupSee Implement the OAuth flow.
GET /load{:http}yesbrowserJWTmarkupThe store owner or authorized user clicks to load the app.
GET /uninstall{:http}noserverJWTJSONThe store owner or authorized user clicks to uninstall the app.
GET /remove_user{:http}noserverJWTJSONThe store owner revokes a user’s access to the app.

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{:http} endpoint. The following is an example request:

Example request: /load callback from BigCommerce
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{:http} endpoint. The following is an example request:

Example request: uninstall callback from BigCommerce
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{:http} 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{:http} endpoint. The following is an example request:

Example request: remove_user callback
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{:http} 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.

Form of payload JWT
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:

EndpointMultiple Users EnabledMultiple Users Not Enabled
GET /load{:http}Compare user to store owner or existing user; if no match, it’s a new user; add them to the app’s database.Matches store owner
GET /uninstall{:http}Compare user to store owner or existing user; only store owner or authorized users can uninstall an app.Matches store owner
GET /remove_user{:http}Compare user to users stored in app database; remove matching user from database.N/A

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

Example: app callback payload
{
  "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

PropertyTypeDescription
audstringThe app API account’s client ID; the intended audience.
issstringThe issuer; the value is always bc.
iatinteger, UNIX timeThe issued at time; when the JWT was issued.
nbfinteger, UNIX timeThe not valid before time; when the JWT became or becomes valid. The value is always the same as iat.
expinteger, UNIX timeThe expiration time; when the JWT becomes invalid. Currently, 24 hours after nbf.
jtistring, UUIDThe JWT ID; a unique identifier for the JWT.
substringIdentifies the subject store in API requests to https://api.bigcommerce.com{:http}; a string of the form stores/{STORE_HASH}.
user.idintegerThe ID of the store owner.
user.emailstringThe email address of the store owner.
user.localestringThe BCP 47 language tag of the store owner.
owner.idintegerThe ID of the store owner.
owner.emailstringThe email address of the store owner.
urlstringAlso known as a deep link. A developer-configured path that provides the app more information about the resource that initiated the load callback.
channel_idintegerThe channel associated with the click event that dispatched the callback. The value is null when a click in the Apps menu sidebar initiates the load callback.

Helpful tools

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

Next step

Resources

Sample apps

Tools

Blog posts