Guide to BigCommerce Webhooks: Features and Best Practices

BigCommerce powers over 60,000 online stores, from small businesses to enterprise brands, and its webhook system is central to building real-time integrations for order management, inventory sync, customer data flows, and more.

However, BigCommerce's lightweight notification-style payloads, aggressive domain blocklisting, and automatic deactivation policies create unique challenges that can catch developers off guard, especially at scale.

This guide covers everything you need to know about BigCommerce webhooks: their features, how to configure them, best practices for reliable processing, and the limitations you'll need to plan around.

What are BigCommerce webhooks?

BigCommerce webhooks are HTTP callbacks that notify your application in real time when events occur in a BigCommerce store. When a customer places an order, a product's inventory changes, or a cart is abandoned, BigCommerce sends an HTTPS POST request to your registered endpoint with details about what happened.

Unlike platforms that send full resource payloads, BigCommerce uses a lightweight notification pattern: webhook payloads contain only the event type and the resource ID. Your application must then call the BigCommerce API to fetch the complete resource data. This design keeps payloads small and secure but requires additional API calls for every webhook you process.

Webhooks are managed primarily through the BigCommerce REST API (V3), though BigCommerce has added a webhook management tab in the control panel's API Accounts section for basic visibility and management. For programmatic integrations, the API remains the primary interface for webhook lifecycle management.

BigCommerce webhook features

Supported webhook events

BigCommerce supports 40+ webhook event types across the following resource categories:

Each category supports wildcard scopes (e.g., store/order/*) to subscribe to all events within a resource type. BigCommerce also provides a special store/hook/deliveryException event that fires when other webhooks fail to deliver.

Webhook payload structure

BigCommerce delivers a lightweight JSON payload with each webhook callback:

{
  "scope": "store/order/created",
  "store_id": "1025646",
  "data": {
    "type": "order",
    "id": 250
  },
  "hash": "dd70c0976e06b67aaf671e73f49dcb79230ebf9d",
  "created_at": 1561479335,
  "producer": "stores/{store_hash}"
}

Key payload fields

The data object structure varies slightly by event type. For example, metafield events include metafield_id and resource_id rather than a simple type and id.

Security and signature verification

BigCommerce provides multiple layers of security for webhook deliveries, including HMAC signature verification, custom headers, and mandatory HTTPS.

HMAC-SHA256 signature verification

BigCommerce signs webhook deliveries using HMAC-SHA256. Each callback includes an X-BC-Signature header containing a hash computed from the request body using your app's client secret. You should validate this signature before processing any webhook to confirm it originated from BigCommerce.

Custom headers

When creating a webhook, you can specify custom headers that BigCommerce will include with every callback delivery. This provides an additional layer of authentication:

{
  "scope": "store/order/created",
  "destination": "https://yourapp.example.com/webhooks",
  "is_active": true,
  "headers": {
    "X-Webhook-Secret": "your-secret-value",
    "Authorization": "Bearer your-token"
  }
}

HTTPS enforcement

All webhook deliveries are sent over TLS-encrypted HTTPS connections, and destination URLs must be served on port 443. Custom ports are not supported. Destination servers must have a valid TLS/SSL certificate; self-signed certificates will cause delivery failures.

Retry logic and delivery behaviour

BigCommerce implements an aggressive retry schedule when webhook deliveries fail. A delivery is considered failed when the destination returns any HTTP status code outside the 2xx range, or doesn't respond at all.

The total retry window spans approximately 48 hours. After all retries are exhausted, the webhook is automatically deactivated and BigCommerce sends an email notification to the address registered with the subscribing app.

Domain blocklisting

BigCommerce monitors webhook delivery success rates using a sliding 2-minute window. If your endpoint's success rate drops below 90%, the entire destination domain is blocklisted for 3 minutes. During this period, no webhooks are delivered to any endpoint on that domain.

Key details about blocklisting:

• Blocklisting is per client_id, not per entire domain across all apps
• Multiple webhook endpoints on the same domain (e.g., domain.com/webhook-1 and domain.com/webhook-2) share the same success/failure calculation
• A minimum of 100 successful requests must exist before blocklisting can trigger
• The store/hook/deliveryException webhook fires with error code 90003 when a domain is blocked

Setting up BigCommerce webhooks

Via the BigCommerce control panel

BigCommerce added a webhook management tab within the API Accounts section of the control panel. This provides basic visibility into existing webhooks and their status. However, for full programmatic control, creating, and managing webhooks at scale, the REST API is the primary tool.

Via the REST API

Create a webhook:

curl -X POST https://api.bigcommerce.com/stores/{store_hash}/v3/hooks \
  -H "X-Auth-Token: {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "store/order/created",
    "destination": "https://yourapp.example.com/webhooks",
    "is_active": true,
    "headers": {
      "X-Webhook-Secret": "your-secret-value"
    }
  }'

List webhooks:

curl -X GET https://api.bigcommerce.com/stores/{store_hash}/v3/hooks \
  -H "X-Auth-Token: {access_token}"

Note: This only returns webhooks created by the current API token. There is no way to list all webhooks across all API tokens for a store.

Important constraints

• Destination URLs must use HTTPS on port 443; custom ports are not supported
• Newly created webhooks can take up to 1 minute to become active
• Maximum of 10 webhooks per unique store_id + client_id + scope combination
• Only 1 webhook per unique store_id + client_id + scope + destination combination
• Webhooks are only visible to the API token that created them

Best practices when working with BigCommerce webhooks

Respond immediately, process asynchronously

BigCommerce expects a fast HTTP 200 response. If your endpoint takes too long, the delivery is marked as failed and triggers retries. Always acknowledge the webhook immediately and queue the actual processing for later.

Verify HMAC signatures

BigCommerce signs webhook payloads with HMAC-SHA256 using your app's client secret. Always verify the X-BC-Signature header before processing.

Node.js

const crypto = require("crypto");

const CLIENT_SECRET = process.env.BC_CLIENT_SECRET;

function verifySignature(rawBody, signature) {
  const computedHash = crypto
    .createHmac("sha256", CLIENT_SECRET)
    .update(rawBody)
    .digest("base64");
  return crypto.timingSafeEqual(
    Buffer.from(computedHash),
    Buffer.from(signature)
  );
}

app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-bc-signature"];

  if (!signature || !verifySignature(req.body, signature)) {
    return res.status(401).send("Unauthorized");
  }

  const event = JSON.parse(req.body);
  res.status(200).send("OK");
  processQueue.add(event);
});

Python

import hmac
import hashlib
import base64
import os

CLIENT_SECRET = os.environ.get('BC_CLIENT_SECRET')

def verify_signature(raw_body, signature):
    computed = base64.b64encode(
        hmac.new(
            CLIENT_SECRET.encode(),
            raw_body,
            hashlib.sha256
        ).digest()
    ).decode()
    return hmac.compare_digest(computed, signature)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-BC-Signature')
    if not signature or not verify_signature(request.data, signature):
        return jsonify({"error": "Unauthorized"}), 401

    process_webhook.delay(request.json)
    return jsonify({"status": "received"}), 200

Implement idempotency using the hash field

BigCommerce can deliver the same webhook multiple times. Use the hash field to detect and skip duplicates:

const processedHashes = new Set();
const HASH_TTL_MS = 5 * 60 * 1000; // 5 minutes

app.post("/webhooks", (req, res) => {
  const { hash } = req.body;

  if (processedHashes.has(hash)) {
    return res.status(200).send("Already processed");
  }

  processedHashes.add(hash);
  setTimeout(() => processedHashes.delete(hash), HASH_TTL_MS);

  res.status(200).send("OK");
  processQueue.add(req.body);
});

For production systems, use a Redis-based cache or database rather than an in-memory set.

Handle 404 errors on follow-up API calls

Because BigCommerce webhooks use a notification pattern, you'll need to call the API to fetch full resource data. Due to eventual consistency, the resource may not be immediately available:

async function fetchResourceWithRetry(resourceType, resourceId, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      const response = await bigcommerceClient.get(
        `/v3/${resourceType}/${resourceId}`
      );
      return response.data;
    } catch (error) {
      if (error.response?.status === 404 && attempt < retries - 1) {
        // Resource not yet propagated; wait and retry
        await new Promise((resolve) =>
          setTimeout(resolve, 1000 * (attempt + 1))
        );
        continue;
      }
      throw error;
    }
  }
}

Subscribe to delivery exception events

Monitor webhook health by subscribing to the store/hook/deliveryException scope. This fires with three error codes:

• 90001: Delivery failed, will retry (rate-limited to once per 10 minutes)
• 90002: All retries exhausted, webhook being disabled
• 90003: Destination domain temporarily blocklisted

BigCommerce webhook limitations and pain points

Lightweight payloads require additional API calls

Problem: BigCommerce webhook payloads contain only the event type and a resource ID. To get any useful data about the order, product, or customer that triggered the event, you must make a separate API call. This means every single webhook effectively doubles your API usage.

Why It Happens: BigCommerce chose this design to keep payloads small, reduce bandwidth, and avoid exposing sensitive data in webhook deliveries. It's a security-first approach, but it shifts significant complexity to the consumer.

Workarounds:

• Design your webhook handler to batch follow-up API calls where possible
• Cache resource data locally to reduce redundant API lookups
• Use BigCommerce's include query parameters to fetch related resources in a single call
• Queue webhook events and process them in batches rather than individually

How Hookdeck Can Help: Hookdeck's transformations can enrich webhook payloads in-flight by calling the BigCommerce API and attaching the full resource data before forwarding to your endpoint, eliminating the need for your application to manage follow-up calls.

Aggressive domain blocklisting

Problem: If your webhook endpoint's success rate drops below 90% within any 2-minute sliding window, BigCommerce blocklists the entire destination domain for 3 minutes. During this period, all webhooks to any endpoint on that domain are paused, including those from different webhook subscriptions that may be working fine.

Why It Happens: BigCommerce uses a domain-wide success ratio calculation rather than per-endpoint tracking. A single failing endpoint can take down webhook delivery for every endpoint on the same domain. The 90% threshold is strict, and the domain-level scope means unrelated integrations can affect each other.

Workarounds:

• Return HTTP 200 immediately for all webhooks, even if downstream processing fails
• Use separate subdomains for different webhook integrations to isolate failure domains
• Implement comprehensive error handling so your endpoint never returns non-2xx responses
• Monitor success rates proactively and alert before reaching the 90% threshold

How Hookdeck Can Help: Hookdeck acts as an intermediary endpoint that always returns a 200 to BigCommerce, completely eliminating the risk of domain blocklisting. Your actual processing endpoints can fail, retry, and recover independently without affecting BigCommerce's delivery status.

Automatic deactivation after inactivity or failed retries

Problem: BigCommerce automatically deactivates webhooks in two scenarios: after all 11 retry attempts are exhausted (approximately 48 hours of failures), and after 90 days of inactivity where no events are sent. Deactivated webhooks silently stop delivering events, and unless you're monitoring is_active status, you may not notice until data goes missing.

Why It Happens: The 48-hour deactivation is a protective measure to stop retrying permanently broken endpoints. The 90-day inactivity cleanup is a platform maintenance policy. Both make sense in isolation but can cause silent failures, particularly in staging environments or for infrequently triggered event types.

Workarounds:

• Implement scheduled health checks that verify all webhooks are still active via the API
• Monitor for BigCommerce's deactivation emails and automate re-activation
• Build a self-healing system that periodically calls GET /v3/hooks and reactivates any disabled webhooks
• For staging environments, trigger test events periodically to prevent inactivity deactivation

How Hookdeck Can Help: Hookdeck's reliable endpoint always accepts deliveries, preventing the retry-based deactivation. Hookdeck's dashboard provides visibility into delivery status, and its alerting capabilities notify you of any issues before they lead to data loss.

Race conditions with eventual consistency

Problem: When your endpoint receives a webhook and immediately calls the BigCommerce API to fetch the resource, the API frequently returns a 404 error. The webhook notification arrives before the resource data has fully propagated through BigCommerce's distributed systems.

Why It Happens: Webhooks are triggered at the moment an event occurs, but BigCommerce's internal data propagation is asynchronous. Database replication, caching layers, and distributed architecture create a window where the webhook arrives faster than the data becomes available via the API.

Workarounds:

• Add a short delay (1-5 seconds) before making follow-up API calls
• Implement retry logic with exponential backoff specifically for 404 responses
• Queue webhook events and process them with a deliberate lag
• Don't treat immediate 404 responses as permanent failures

How Hookdeck Can Help: Hookdeck's delay feature can introduce a configurable pause between receiving the webhook and forwarding it to your endpoint, giving BigCommerce's systems time to achieve consistency before your application attempts to fetch the data.

Duplicate webhook deliveries without built-in deduplication

Problem: BigCommerce can send the same webhook event multiple times due to network issues, retry logic, and system recovery after temporary outages. There is no built-in deduplication mechanism, and the platform explicitly follows at-least-once delivery semantics.

Why It Happens: Network glitches can cause BigCommerce to miss your 200 response, triggering a retry of an event you've already processed. System outages and recovery processes can also generate duplicate sends. The retry mechanism has no awareness of whether the original delivery was actually received.

Workarounds:

• Use the hash field in the payload to detect and skip duplicates
• Maintain a temporary cache (e.g., Redis) of recently processed webhook hashes
• Design all webhook handlers to be idempotent so processing the same event twice produces the same result
• Use database unique constraints on business identifiers to prevent duplicate records

How Hookdeck Can Help: Hookdeck's deduplication feature automatically detects and filters duplicate webhooks based on configurable criteria, ensuring your endpoint only receives each unique event once.

API rate limits create processing bottlenecks

Problem: Because each webhook requires at least one follow-up API call to fetch resource data, high-volume webhook scenarios quickly exhaust BigCommerce's API rate limits. During peak shopping events like flash sales or Black Friday, the combination of webhook volume and required API calls can create a processing bottleneck where webhooks queue up faster than you can process them.

Why It Happens: BigCommerce's lightweight payload design means every webhook generates API traffic. API rate limits refresh every 30 seconds, and with OAuth-authenticated apps, the limits are stricter. A burst of order webhooks during a sale event can easily exceed these limits.

Workarounds:

• Batch follow-up API calls and process webhooks in groups rather than individually
• Implement rate-limit-aware processing with backoff using the X-Rate-Limit-Time-Reset-Ms response header
• Cache frequently accessed resources locally to reduce API calls
• Use webhook event filtering to subscribe only to the events you actually need
• Request higher rate limits from BigCommerce support for enterprise accounts

How Hookdeck Can Help: Hookdeck's rate limiting feature can throttle webhook delivery to your endpoint at a rate that matches your API budget, preventing bursts from overwhelming your processing pipeline.

No webhook delivery logs or visibility

Problem: BigCommerce provides no delivery logs, no webhook activity dashboard, and no API endpoint to query delivery history. If a webhook fails or goes missing, you have no way to trace what happened on the BigCommerce side. The only visibility mechanism is the store/hook/deliveryException webhook, which itself can fail to deliver.

Why It Happens: BigCommerce's webhook infrastructure is designed as a fire-and-forget notification system. Logging and delivery tracking are not built into the platform, leaving developers to build their own observability layer.

Workarounds:

• Log every incoming webhook on your end with full payload, headers, and timestamps
• Subscribe to store/hook/deliveryException for failure notifications
• Implement reconciliation jobs that compare expected events against received events
• Build your own webhook delivery dashboard using logged data

How Hookdeck Can Help: Hookdeck's dashboard provides complete visibility into every webhook event, including delivery status, response codes, latency, payload inspection, and full request/response history with search and filtering capabilities.

Webhooks scoped to API tokens with no global visibility

Problem: Webhooks are tied to the API token that created them. You can only list and manage webhooks created by your own token. There is no way to see all webhooks registered on a store across all apps and API tokens, making auditing and debugging difficult in multi-app environments.

Why It Happens: BigCommerce's webhook system was designed with multi-tenant app isolation in mind. Each app's webhooks are sandboxed to its own API credentials. While this provides security, it eliminates cross-app visibility for store owners and platform administrators.

Workarounds:

• Use a single API token for all webhook management where possible
• Maintain an external registry of all webhook subscriptions across apps
• Conduct regular audits by querying webhooks from each known API token
• Document webhook ownership as part of your integration architecture

How Hookdeck Can Help: Hookdeck provides a centralised dashboard showing all webhook connections and events in one place, regardless of which API token created them, giving you the global visibility that BigCommerce's native system lacks.

Testing BigCommerce webhooks

Use a request inspector

Before building your handler, inspect actual BigCommerce webhook payloads using Hookdeck Console:

1. Create a temporary Console URL
2. Register it as a webhook destination via the BigCommerce API
3. Trigger events in your store (create a test order, update a product)
4. Inspect the payload structure, headers, and timing in the Console

Test with local development

Use a tunnelling tool to expose your local development server:

1. Start your local webhook handler
2. Use a tool like the Hookdeck CLI to create a public URL pointing to your local server
3. Register the tunnel URL as your webhook destination
4. Trigger events and debug in real time with full logging

Validate retry and failure scenarios

Test how your system handles failure modes:

• Return non-200 status codes to observe BigCommerce's retry behaviour
• Simulate slow responses to test timeout handling
• Send duplicate payloads with the same hash to verify your deduplication logic
• Test domain blocklisting behaviour by intentionally failing multiple webhooks

Monitor with delivery exception webhooks

Always include a store/hook/deliveryException webhook in your test setup. This gives you immediate feedback when deliveries fail, including whether your domain has been blocklisted (error code 90003).

Conclusion

BigCommerce webhooks provide a solid foundation for real-time event-driven integrations with e-commerce stores. The platform supports 40+ event types across all major resources, implements a thorough retry schedule spanning 48 hours, and offers useful features like wildcard scopes and delivery exception monitoring.

However, the lightweight payload design, aggressive domain blocklisting, automatic deactivation policies, lack of delivery visibility, and API rate limit interactions create real operational challenges, particularly for high-volume stores and complex multi-app environments. Developers need to invest significant effort in building idempotent handlers, managing follow-up API calls, implementing deduplication, and monitoring webhook health.

For straightforward integrations with moderate event volumes, BigCommerce's native webhook system works well when paired with the best practices outlined above. For production deployments that demand reliability, visibility, and operational confidence, Hookdeck provides the infrastructure layer that BigCommerce's webhook system is missing.