Skip to main content

Create Custom Events with App Hooks

caution

Bold encourages developers to use integrations in order to extend Bold Checkout, instead of plugins. There are two types of integrations: private and public. For more information, refer to Extend Bold Checkout.

An application hook (or app hook) is a custom event that you can use to communicate between Bold Checkout and your plugin. It allows a plugin with custom frontend components to participate in the event-action loop.

Checkout events trigger when a customer moves through the frontend of a Bold Checkout experience. However, certain plugins provide functionality via custom frontend components, which do not automatically trigger events. In order for a developer to send information about events from a custom frontend component to their plugin, they must use an application hook.

This page provides a potential use case for application hooks and outlines the steps for setting one up.

Use case​

For this scenario, imagine a developer that wants to create a publicly-available plugin that allows alcoholic beverage distributors to verify that a customer is of legal drinking age. The developer wants to add a tag to each order indicating that the customer is of age.

With this example in mind, the following diagram and steps show the flow of information between the plugin and Bold Checkout:

  1. While checking out, a customer checks a box that indicates they are of legal drinking age.
  2. The plugin frontend registers this action, and the plugin calls the Dispatch App Hook Event endpoint with the details of the custom event.
  3. Bold Checkout sends an app_hook event to the plugin.
  4. The plugin responds with an add_tag action, marking the order with a tag of age_verified. For more information about the add_tag action, refer to the Plugin Actions reference.
  5. Bold Checkout adds the age_verified tag to the order and returns the application_state of the order.

This example is used throughout the remainder of the page.

Create an API access token​

Using app hooks requires making calls to the Checkout Frontend API, which requires an API access token to authenticate all calls. This API access token must be obtained and managed in addition to the client ID and client secret already assigned to your plugin.

If your plugin is private, follow the instructions in Making API Calls to get your API access token.

If you plugin is public, follow the instructions in Build Public Integrations to get your API access token.

Trigger the event​

Each time you want to trigger an event using an app hook, make a call to the Dispatch App Hook Event endpoint.

The following code snippet shows a call to the Dispatch an App Hook Event endpoint that notifies a plugin when someone has verified their age by checking a box. In this snippet,

  • "uuid" is the plugin's client ID.
  • "hook" is the name of your custom event.
  • "data" is the information you would like to communicate to the plugin, organized in key-value pairs.
curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/app_hook' \
     --header 'Authorization: Bearer {api_access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "uuid": "93225ea4-d701-41f9-a30a-bfe66f5d0479",
         "hook": "age_verififed",
         "data": {
             "tag_name": "over_legal_minimum",
             "tag_value": true
         }
     }'

Handle the event and respond with an action​

When Bold Checkout receives your call to the Dispatch App Hook Event endpoint, it sends an app_hook event to your plugin. Your plugin can handle an app_hook event like any other event, with the exception that it must also determine which app hook was triggered, if more than one exists. The "hook" field is helpful for identifying the various app hooks.

For more details about handling events, refer to Implement the Event-Action Loop.

After the plugin responds with an action, Bold Checkout responds to the original Dispatch an App Hook Event call with an updated version of the application_state.

Reflect the changes in the frontend​

If your plugins uses actions that result in a change to information displayed on the frontend, ensure that your plugin triggers a refresh of the page or otherwise updates the frontend.