Webhooks notify you of important changes that have occurred outside of your application for accounts you’ve connected to. You’ll also receive webhooks for changes you make with the API, but you shouldn’t need those since all API requests you make will receive a synchronous response.

Types of webhooks

Type Payload Description
account.closed account Sent when an account has been closed or the owner has revoked access to your application. This payload will only include the account id instead of the full account object.

Note: this will change to account.deauthorized beginning June 1st, 2017.
account.updated account Sent when an account is updated.
account.plan.downgraded account Sent when an account is downgraded.
account.plan.upgraded account Sent when an account is upgraded.
order.created order Sent when a new order is placed.
order.updated order Sent when an order changes.
product.created product Sent when a new product is created.
product.updated product Sent when a product is updated, either by the account or when it’s part of a new order.
product.deleted product Sent when a product is deleted. This payload will only include the product id instead of the full product object.

Receiving webhooks

Webhooks will be sent as an HTTP POST request to the webhook_url for your application in the following JSON format:

  "account_id": "12345",
  "type": "order.created",
  "payload": { ... }

Verifying webhooks

In order to ensure the webhook you received is legit, we suggest you verify its signature. To do that, create an HMAC signed using the SHA256 hash algorithm, using your application’s client_secret and the body of the webhook request as keys, and make sure it matches the webhook’s X-Webhook-Signature header.

Here are a few examples of creating a signature you can then validate against the header:


require 'openssl'
require 'base64'

sha256 = OpenSSL::Digest::SHA256.new
body = request.body.read
signature = OpenSSL::HMAC.hexdigest(sha256, secret, body)


import hmac
from hashlib import sha256

body = request.data
signature = hmac.new(secret, body, sha256).hexdigest()


var crypto = require('crypto');
var hmac = crypto.createHmac('sha256', clientSecret);
var signature = hmac.digest().toString('hex');


$body = file_get_contents('php://input');
$signature = hash_hmac('sha256', $body, $secret);

Responding to webhooks

To acknowledge you received the webhook without any problem, your server should return a 2xx HTTP status code. Any response code other than that will tell Big Cartel that you didn’t receive the webhook, and we’ll continue to retry it at degrading intervals for the next 7 days.