Register for Webhooks

Registering to listen to a webhook enables the Bold Subscriptions API to alert you when something significant happens in your store. This document outlines the steps required to subscribe to these webhooks and the triggers that cause each webhook to be sent.

note

To view the full list of webhooks and their sample callback responses, the Create Webhook Subscription API specification. View callback schemas in the Callbacks section, and view example responses in the Callback payload samples section.

Subscribe to Bold Subscriptions Webhooks

Use the following steps to gather additional information about the webhooks and effectively use them to monitor your customer subscriptions.

Prerequisites

Before you get started, complete the steps outlined in the Subscriptions Getting Started guide.

Get webhook topics

Call the List Webhook Topics endpoint to return a full list of the webhooks and the ID assigned to each. Make note of the ID of the webhook you would like to subscribe to.

Create a webhook subscription

To receive an HTTP request containing information about the event when a webhook is triggered, use the Create Webhook Subscription endpoint. Provide the following information in the request body of the API call:

• webhook_topic_id — the ID identified from the Get webhook topics endpoint.
• callback_url — the url where you would like each response to be sent. A secure protocol (https) is required on your callback url.
• shared_secret — a string that Bold uses to create a unique signature (x-bold-signature) based on your call. x-bold-signature is sent as a request header and is a SHA-256 hash calculated using the payload and shared-secret. When you receive a request, you can calculate the correct hash and confirm that this request is from Bold.

For example, this API call might be used to begin listening for new customer accounts created:

curl --request POST 'https://api.boldcommerce.com/subscriptions/v1/shops/{shopIdentifier}/webhooks/subscriptions' \
     --header 'Authorization: Bearer {api_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "webhook_subscription": {
             "callback_url": "https://webhooks.example.com",
             "webhook_topic_id": 4,
             "shared_secret": "exMh194qw8JD@A50dA^P"
         }
     }'

Trigger Bold Subscriptions webhooks

The following table shows the webhooks that are available and the ways they are triggered:

Webhook	How to trigger
customer_created	Create a customer and complete an order containing one or more subscription products for that order.
customer_updated	Change customer information, including name, email, or phone number.
subscription_cancelled	Cancel a subscription containing one or more subscription products.
subscription_created	Complete an order containing one or more subscription products.
subscription_credit_card_updated	(Bold Checkout only) Update the payment method of a subscription.
subscription_expiring_payment	Occurs when the payment method of a subscription is due to expire, prompting an email notification.
subscription_frequency_updated	Update the next_order_datetime of a subscription containing one or more subscription products.
subscription_order_created	Complete an order containing one or more subscription products for any customer. Triggers every time a subscription order is processed.
subscription_order_max_retries_reached	Upon a certain number of failures to process a specific subscription order. Max retries can be set in the Bold Subscriptions admin.
subscription_order_transaction_failed	Upon failure of a specific subscription order transaction.
subscription_payment_failed	Upon failure of the payment method for the initial subscription transaction.
subscription_paused	Pause a subscription containing one or more subscription products.
subscription_payment_method_updated	Update the payment information for a subscription with one or more subscription products.
subscription_quantity_updated	Change the quantity of a subscription product for a given subscription.
subscription_reactivated	Reactivate a cancelled subscription containing one or more subscription products.
subscription_resumed	Resume a paused subscription containing one or more subscription products.
subscription_shipping_address_updated	Change the shipping address of a subscription with one or more subscription products.
subscription_skipped	Skip a future ship date for a subscription containing one or more subscription products.
subscription_upcoming_order	Occurs when next_order_datetime is equal to the current datetime.
subscription_updated	Make any edit to a subscription with one or more subscription products.
subscription_line_items_added	Update an existing subscription with a new product from the customer portal or the Create Line Items endpoint.

note

• As shown above, some actions can trigger more than one webhook. For example, completing an order containing one or more subscription products triggers subscription_created and subscription_order_created.

• The subscription_payment_method_updated webhook is not supported by default for all Shopify shops installed prior to January 15th 2024 (2024-01-15). Please submit a support request for access.

Retry attempts

If a webhook request does not respond, Bold retries the request up to 5 times.

The times before each retry attempt are listed below:

Attempt	Time before retrying (seconds)
1	3
2	10^2 = 100
3	10^3 = 1000
4	10^4 = 10000
5	10^5 = 100000