Skip to main content

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:

WebhookHow to trigger
customer_createdCreate a customer and complete an order containing one or more subscription products for that order.
customer_updatedChange customer information, including name, email, or phone number.
subscription_cancelledCancel a subscription containing one or more subscription products.
subscription_createdComplete an order containing one or more subscription products.
subscription_credit_card_updated(Bold Checkout only) Update the payment method of a subscription.
subscription_expiring_paymentOccurs when the payment method of a subscription is due to expire, prompting an email notification.
subscription_frequency_updatedUpdate the next_order_datetime of a subscription containing one or more subscription products.
subscription_order_createdComplete an order containing one or more subscription products for any customer. Triggers every time a subscription order is processed.
subscription_order_max_retries_reachedUpon a certain number of failures to process a specific subscription order. Max retries can be set in the Bold Subscriptions admin.
subscription_order_transaction_failedUpon failure of a specific subscription order transaction.
subscription_payment_failedUpon failure of the payment method for the initial subscription transaction.
subscription_pausedPause a subscription containing one or more subscription products.
subscription_payment_method_updatedUpdate the payment information for a subscription with one or more subscription products.
subscription_quantity_updatedChange the quantity of a subscription product for a given subscription.
subscription_reactivatedReactivate a cancelled subscription containing one or more subscription products.
subscription_resumedResume a paused subscription containing one or more subscription products.
subscription_shipping_address_updatedChange the shipping address of a subscription with one or more subscription products.
subscription_skippedSkip a future ship date for a subscription containing one or more subscription products.
subscription_upcoming_orderOccurs when next_order_datetime is equal to the current datetime.
subscription_updatedMake any edit to a subscription with one or more subscription products.
subscription_line_items_addedUpdate 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:

AttemptTime before retrying (seconds)
13
210^2 = 100
310^3 = 1000
410^4 = 10000
510^5 = 100000