Google Cloud Platform (GCP) Pub/Sub Webhooks Overview

Google Cloud Pub/Sub is a fully managed, asynchronous messaging service that enables seamless communication between distributed systems through the exchange of event data. It allows applications to publish messages to a topic, which other services can then subscribe to, ensuring that important events are delivered reliably and at scale.

In an eCommerce ecosystem, where merchants and applications often need to coordinate real-time updates (such as order status, inventory changes, or customer events), Pub/Sub can serve as a critical backbone for communication by decoupling the publisher (e.g., BigCommerce) from subscribers (e.g., merchant systems, third-party apps), this architecture ensures that:

• Applications can react to import events ---- like new orders, product updates, or payment confirmations --- without direct dependencies
• Scalability is inherent, allowing merchants to handle sudden spikes in demand (e.g., during holiday sales) without service degradation
• Messages are durable and persist until delivered, reducing the risk of lost information during outages and processing delays
• Filtering capabilities ensure that subscribers receive only relevant events, improving efficiency
• Storage and retry mechanisms guarantee reliable delivery, even when subscribers' applications experience temporary downtime
• By leveraging Google Cloud Pub/Sub, merchants and app developers can build more resilient, responsive, and scalable systems --- delivering a better experience to end customers while simplifying backend complexity

Key benefits

• Decoupled Architects: BigCommerce, merchants, and apps can operate independently, enhancing system flexibility and maintainability
• Scalability: Automatically manages the load, accommodating high-throughput scenarios without manual intervention
• Reliably: Ensures message delivery with built-in acknowledgment and retry mechanisms, reducing the risk of data loss
• Real-Time processing: Enables immediate reaction to events, facilitating timely updates and actions

Real-world examples

Example 1: Product updates

Example 2: Order creation

Example 3: Channel management

Example 4: Multi-vendor order fulfillment

Prerequisites

• Google Cloud Platform account
• Billing enabled for the GCP
• Necessary IAM roles (Pub/Sub admin)
• For app partners, access to the GCP project or service account credential is provided

Helpful

• gCloud CLI
• Pub/Sub API enabled

BigCommerce

Initiate your app

You can initiate your app with Google Pub/Sub to allow for sending and receiving webhook traffic by following the procedure below.

1. Navigate to your store’s control panel, and go to Settings > Store-level API accounts.
2. Create a new API account (opens in a new tab) or use an existing one.
   • Click on the API Account name > Event subscriptions tab.
   • In the Google Cloud Pub/Sub panel, copy the BigCommerce service account (webhook-deliveries@bigcommerce-platform.iam.gserviceaccount.com).

Google Cloud Pub/Sub

The following steps discuss how to manage projects, topics, and subscriptions using the Google Cloud console. You can use the Google Cloud CLI, methods, and/or APIs to perform the same tasks. For additional guidance, see the Google Cloud Pub/Sub (opens in a new tab) documentation.

Creating a project

To create a project, you must have the resourcemanager.projects.create permission. This permission is included in roles like the Project Creator role (roles/resourcemanager.projectCreator). The Project Creator role is granted by default to the entire domain of a new organization resource and to free trial users.

To create a new project go to the Manage resources (opens in a new tab) page in the Google Cloud console.

In the Google Cloud console, perform the following steps:

1. If you do not have a free trial, you must first select the organization resource from the Select organization drop-down list.
2. Click Create Project.
3. In the New Project window, enter a project name and select a billing account if required. The project name must be between 4 and 30 characters and can include letters, numbers, single quotes, hyphens, spaces, or exclamation points.
4. In the Location box, specify the parent organization or folder resource that will serve as the hierarchical parent of the new project. If the option No organization is available, you can select it to create the project at the top level of its own resource hierarchy
5. Click Create.

For more details on how to create a project see, the Console (opens in a new tab) instructions.

Creating a topic

Topics can represent different events such as order created, inventory updated, etc. You must create a topic before you can publish or subscribe to it.

To create a topic, follow these steps:

1. In the Google Cloud console, go to the Pub/Sub Topics (opens in a new tab) page.
2. Click Create topic.
3. In the Topic ID field, enter an ID for your topic.
4. Ensure Add a default subscription is enabled.
5. Click Create topic.

For more details on how to create a topic see, Create a topic (opens in a new tab).

Once you create a topic, add BigCommerce as a principal.

You can subscribe to webhook subscriptions after integrating your app with Google Cloud Pub/Sub. See the following GraphQL example:

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
 
mutation Webhook {
  webhook {
    createPubSubWebhook(
        input: {
            destination: "projects/projectName/topics/webhookName"
            isActive: true
            scope: "store/metafield/created"
        }
    ) {
        errors {
            ... on AlreadyExistsError {
                message
            }
            ... on ValidationError {
                message
            }
            ... on PubSubTopicNotFoundError {
                topic
                message
            }
 
        }
        webhook {
            destination
            clientId
            createdAt
            id
            scope
            status
            updatedAt
                 }
          }
     }
}

For a complete reference of all BigCommerce webhook events and their callback payloads, see Webhook Events.

Creating a subscription

By default, subscriptions use pull delivery, unless you explicitly set a push configuration. A push configuration grants BigCommerce access to publish webhooks to your Google Pub/Sub topic. The following section describes how to create a push subscription.

Creating a push subscription

To create a push subscription, complete the following steps:

1. In Google Cloud console, go to the Subscriptions (opens in a new tab) page.
2. Click Create subscription.
3. For the Subscription ID field, enter a name.
4. Choose or create a topic from the drop-down menu.
5. Select the Delivery type as Push.
6. Specify an endpoint URL.
7. Retain all other default values.
8. Click Create.

You can also create a subscription from the Topics (opens in a new tab) section. This shortcut is useful for associating topics with subscriptions.

1. In the Google Cloud console, go to the Topics (opens in a new tab) page.
2. Click the three dots next to the topic and select Create subscription.
3. Enter the Subscription ID. For information on how to name a subscription, see Guidelines to name a topic or a subscription (opens in a new tab).
4. Select the Delivery type as Push.
5. Specify an endpoint URL.
6. Retain all other default values.
7. Click Create.

For more details on how to create a push subscription see, Create push subscriptions (opens in a new tab).

Deleting a subscription

If you try to create a subscription with the same name as the one that you just deleted, expect an error for a brief period.

To delete a subscription, complete the following steps:

1. In the Google Cloud Console, got to the Subscriptions (opens in a new tab) page.
2. Select the subscription to delete.
3. Click Delete.

For more details on how to delete a subscription, see Delete subscriptions (opens in a new tab).

Managing project access control

You can use the Google Cloud console to manage access control for your topics and projects.

To set access controls at the project level, complete the steps below:

1. In the Google Cloud Console, got to the IAM (opens in a new tab) page.
2. Select your project.
3. Click Add.
4. Type in one or more principal names.
5. In the Select a role list, select the role you want to grant.
6. Click Save.
7. Verify that the principal is listed with the role that you granted.

To set access controls for topics and subscriptions, follow the steps below:

1. You can use the Google Cloud console, go to the Pub/Sub Topics (opens in a new tab) list.
2. If needed, select your Pub/Sub-enabled project.
3. Perform one of the following steps:
   • To set roles for one or more topics, select the topics
   • To set roles for a subscription attached to a topic, click the topic ID. In the Topic details page, click the subscription ID. The Subscription details page appears.
4. If the info panel is hidden, click the Show info panel.
5. In the Permissions tab, click Add principal.
6. Type in one or more principal names.
7. In the Select a role list, select the role you want to grant.
8. Click Save.

View metrics

To view a single Pub/Sub metric by using the Google Cloud console, perform the following steps:

1. In the Google Cloud Console, go to the Monitoring (opens in a new tab) page.
2. In the navigation pane, select Metrics explorer.
3. In the Configuration section, click Select a metric.
4. In the filter, enter Pub/Sub.
5. In Active resources, select Pub/Sub Subscription or Pub/Sub Topic.
6. Drill down to a specific metric and click Apply.

For more details on monitoring the dashboard see Cloud monitoring (opens in a new tab).

To see what metrics Pub/Sub reports to Cloud Monitoring, see the Pub/Sub metrics list (opens in a new tab) in the Cloud Monitoring documentation.

To see the details for the pubsub_topic, pubsub_subscription, or pubsub_snapshot monitored resource types, see Monitored resource (opens in a new tab) types in the Cloud Monitoring documentation.

Resources

• Google Cloud Pub/Sub Documentation (opens in a new tab)
• GCP CLI (opens in a new tab)
• Webhook Events