Register for Webhooks

Bold Checkout webhooks allow you to be notified when something significant happens on your store.

This page outlines the process for subscribing to Bold Checkout webhooks and provides detailed information about each one.

note

The content on this page refers to integration webhooks, which use the same method of authentication as all Bold integrations. This method of authentication is covered in the Checkout Getting Started guide.

If you want to use plugin webhooks, which require the same method of authentication as plugins, refer to the Webhook Subscriptions section of the Classic Checkout API documentation.

Subscribe to Bold Checkout webhooks

The following sections outline the steps for registering to listen to Bold Checkout webhooks.

Requirements

Bold Checkout requires both an API access token and a shared secret in order for your integration to receive webhooks. Failure to retrieve and configure your shared secret can cause the webhooks to fail.

For more information on retrieving this token, refer to the Quick Start for private integrations, and Building Public Integrations for public integrations.

Prerequisites

Complete the steps outlined in the Checkout Getting Started guide.

Configure the shared secret

You must provide your shared secret to the Checkout Backend API via the Configure Integration Settings endpoint. The shared secret prevents unauthorized requests to your callback URL. Bold Checkout uses your shared secret and the payload of each callback request to calculate a SHA-256 hash, which is passed to you in the header of each callback request as an HMAC-based signature. Bold uses the same shared secret for all Checkout webhooks sent to your integration.

The following snippet shows an example of the call you must make to provide your shared secret to Bold:

curl --request POST 'https://api.boldcommerce.com/checkout/shop/{shop_identifier}/integration/config' \
     --header 'Authorization: Bearer {api_access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "shared_secret": "replace_with_your_shared_secret"
     }'

Get a list of webhook topics

Call the List Webhook Topics endpoint to see the full list of Bold Checkout webhooks and the IDs associated with each. You need the webhook_topic_id of the webhook(s) you want to listen to.

Register for the webhook

To register for a Bold Checkout webhook, call the Create Webhook endpoint using the ID you found in the previous step. Provide a callback URL, which is where the webhook payload will be sent when it triggers.

The following snippet demonstrates how to register for the order/abandoned webhook:

curl --request POST 'https://api.boldcommerce.com/checkout/shop/{shop_identifier}/webhooks' \
     --header 'Authorization: Bearer {api_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "webhook_topic_id": 5,
         "callback_url": "https://webhooks.example.com"
     }'

Verify the request

Bold signs all webhook requests using the Signing HTTP Messages IETF draft standard (Version 12). Bold creates the signature using the payload of your request and the shared secret you provided when configuring the Bold Checkout webhooks. This signature is created using the SHA-256 algorithm.

When you receive a callback request, the header of the request contains an HMAC-based signature and other important information in the following format:

keyId="shared_secret", algorithm="hmac-sha256", signature="MXpePJs99hUcgzst2IDOU3HMj0kmcxyLc1ZpaWq3OeU", headers="(request-target) date"

You can use your shared secret, the callback payload, and the same SHA-256 algorithm to calculate a hash and verify that the request is indeed from Bold. The following JavaScript snippet (which uses the node-http-signature library) shows an example of programmatically verifying that the request you receive is from Bold:

const httpSignature = require("http-signature");
const verify_signature = (req, res, next) => {
  // Verify Bold Checkout's HTTP signature.
  try {
    // Avoid failing validation if date header contains `request-target`.
    const tempURL = req.url;
    req.url = req.originalUrl;
    const parsed = httpSignature.parse(req);
    req.url = tempURL;

    // Verify that the request originated from Bold Checkout.
    if (httpSignature.verifyHMAC(parsed, process.env.SHARED_SECRET)) {
      next();
    } else {
      res.status(401).end();
    }
  } catch (error) {
    res.status(401).end();
  }
};
const log = (req, res, next) => {
  console.log(req.method, req.url);
  next();
};
module.exports = {
  log,
  verify_signature,
};

Update or delete webhooks

To get the full list of your current webhook subscriptions, call the List Webhooks endpoint. This endpoint returns a list of the applicable webhooks, including information about when each webhook subscription was created or updated.

With this information, you can update the callback URL of a webhook or delete a webhook.

Available Bold Checkout webhooks

The Checkout Admin API provides the following webhooks:

• order/processed
• order/created
• order/fulfilled
• order/abandoned
• order/failed
• gift_card/created

The following subsections contain additional information about when each webhook triggers and additional steps that must be taken to set up the webhook (if applicable). Examples of the callback response payloads are included under the Create Webhook endpoint, in the Callbacks section.

Order processed webhook

The order/processed webhook triggers when the customer clicks the "Place Order" button or otherwise confirms their purchase at the end of the checkout flow. In a headless checkout scenario, this webhook triggers upon completion of the Process Order endpoint call.

Order created webhook

The order/created webhook triggers when Bold Checkout sends the order to the store's ecommerce platform. If you are registered for both the order/processed and order/created webhook, you will receive both callbacks in short succession.

Order fulfilled webhook

The order/fulfilled webhook triggers when the order is marked as "fulfilled" in the store's ecommerce platform. At this point in the order lifecycle, number of items fulfilled equals the number of items in the order.

note

Some platforms allow you to change your setting to mark an order as "fulfilled" as soon as it receives the order, which would change the timing of this webhook callback.

Order abandoned webhook

The order/abandoned webhook triggers if a customer abandons their cart. While Bold Checkout offers abandoned cart emails out-of-the-box, merchants may want more control over the customer communication.

Bold Checkout considers an order abandoned one hour after a customer leaves the store with an item still in their cart. After an hour, the order enters a queue to be dispatched as an abandoned cart webhook. This queue of webhooks is dispatched every five minutes.

Once your callback URL receives the abandoned cart webhook request, it is up to your implementation to take action, such as sending out an email or SMS message prompting the customer to finish the transaction.

Disable Bold Checkout abandoned cart emails

note

You must disable the Bold Checkout abandoned cart emails to receive callbacks from order/abandoned. This is a required step.

In order to prevent customers from receiving multiple emails about abandoned carts, change the appropriate settings in Bold Checkout:

1. In the Bold Checkout app, navigate to Orders, then Abandoned cart settings.
2. Toggle off the Abandoned cart emails are enabled setting.

Order failed webhook

The order/failed webhook indicates that the order was not successful. This webhook can trigger at various points in the order lifecycle, including the following:

• Failure to create the order in the platform.
• Failure to authorize the customer's payment method.
• Failure to capture the customer's payment.
• Failure to push a charge to the order.

If you receive an order/failed webhook response, retrieve the public_order_id from the callback response and reach out to the Bold Support team.

Gift card created webhook

note

Gift card functionality is available by request only, with some exceptions (i.e. stores on Shopify with Bold Cashier have this functionality enabled automatically). If you would like to create gift cards, please reach out to your account manager to request gift card functionality.

The gift_card/created webhook triggers every time someone purchases a gift card on your store. This webhook will only trigger if you have gift cards enabled on your store.

Before you subscribe to the gift_card/created webhook, complete the following steps to enable gift cards on your store:

1. In your store's ecommerce platform, add a product representing a gift card.
2. In the Bold Checkout admin, click Payment options, then Gift cards in the left-hand menu. Use this page to connect a gift card provider (either Bold Gift Cards or GiveX).
3. On the same page, search for the SKU of the product you created in Step 1 and mark it as a gift card.

These steps enable gift cards on your store. You can then register to listen to the gift_card/created webhook.