Webhooks

Overview

Webhooks allow your application to subscribe to events that occur within Rokt Catalog, giving you real-time updates whenever a change is made by Rokt Catalog or a connected Brand. The webhook topics available to you depend on whether you are integrating as a Partner (storefront) or a Brand (supplier).

Partner Webhooks

Partners are storefronts that sell Brand products through Rokt Catalog. Subscribe to these webhooks to keep your storefront in sync with Catalog: automatically receiving new product data, tracking order status, and providing customers with up-to-date shipping information.

product/create

Fires when you are approved to sell a Brand's product and you click the Add to store button next to that product in the Inventory tab of the Rokt Catalog app. The webhook delivers the full product payload, including title, description, images, variants, pricing, and inventory, so your application can create a matching product listing on your storefront automatically.

This is typically the first webhook Partners set up.

product/update

Fires when a Brand modifies a product that you are currently selling. Changes can include updated pricing, revised descriptions, new images, inventory quantity adjustments, or variant changes. The webhook delivers the full updated product payload so your application can apply the changes to your storefront.

Subscribe to this webhook to ensure your product listings always reflect the Brand's latest information. Without it, your storefront could display outdated prices or descriptions, leading to customer confusion and potential order issues.

order/update

Fires when any change occurs on an order that was placed through your storefront. This includes status changes (e.g., moving from processing to completed), shipping address corrections, or modifications made by the Brand or Catalog. The webhook delivers the full updated order object.

Subscribe to this webhook to keep your internal order records synchronized with Catalog. This is especially important for displaying accurate order status to your customers.

fulfillment/create

Fires when a Brand creates a new shipment for an order placed through your storefront. The webhook delivers the fulfillment data, including the shipping carrier, tracking number, tracking URL, and the specific line items included in the shipment. An order may have multiple fulfillments if the Brand ships items separately.

Subscribe to this webhook to send shipping confirmation emails to your customers and display tracking information on your storefront. This is essential for providing a complete post-purchase experience.

fulfillment/update

Fires when a Brand updates an existing shipment, for example, correcting a tracking number, changing the shipping carrier, or updating the shipment status. The webhook delivers the full updated fulfillment object.

Subscribe to this webhook to ensure the tracking information displayed to your customers stays accurate throughout the delivery process.

Brand Webhooks

Brands are suppliers whose products are sold by Partners through Rokt Catalog. Subscribe to these webhooks to receive incoming orders and stay informed about order lifecycle changes so you can manage fulfillment.

order/create

Fires when a connected Partner places an order containing your product. The webhook delivers the full order object, including line items, quantities, the customer's shipping address, and order metadata. This is the primary webhook for Brands: it is how you receive new orders from the Catalog network.

Subscribe to this webhook to ingest incoming orders into your fulfillment system. Without it, you would need to poll the Orders API to discover new orders, which adds latency and complexity.

order/update

Fires when a change is made to an order you received from a Partner. Updates can include shipping address corrections, line item modifications, or status changes initiated by the Partner or Catalog. The webhook delivers the full updated order object.

Subscribe to this webhook to keep your fulfillment system in sync with the latest order details. For example, if a customer updates their shipping address before the order ships, this webhook ensures you ship to the correct location.

order/cancel

order/cancel is accepted when you register a webhook, but Rokt Catalog does not currently send events on this topic. Cancellations reach you through order/update: the order object arrives with cancelled_at set and, where available, a cancel_reason.

Watch for cancelled_at on order/update events to halt fulfillment processing for cancelled orders and update your inventory accordingly. Acting on cancellations promptly prevents unnecessary shipments and reduces the need for returns.

Webhook Registration

There are two methods to register a webhook:

Method 1: Rokt Catalog App

To register a new webhook:

1. Log into your account on the Rokt Catalog app.
2. Visit the Developer tab in Settings. You can find Settings in the dropdown under your brand's name in the top right.
3. Scroll down to the section called Add Webhooks.

4. Click on Add webhook and enter in the information requested.
5. Click Run test in the modal and ensure you receive a confirmation message that the webhook has been successfully verified. If you get an error, please make changes accordingly.

Method 2: Terminal

You can perform the same actions as above using commands in your terminal. You can POST a request to the /webhooks/ endpoint with all the necessary information. An example of what this may look like is:

curl https://api.shopcanal.com/platform/webhooks/ \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-canal-app-id: xxxx-xxxx-xxxx-xxxx' \
  --header 'x-canal-app-token: your_canal_api_access_token' \
  --data '{
    "topic": "product/create",
    "address": "https://api.retailer.com/webhook-sink"
  }'

You can find more information in the developer docs.

Webhook Verification

Before you respond to a webhook, you need to verify that the webhook was sent from Rokt Catalog. Catalog sends the following headers in the request: x-canal-app-id, x-canal-topic, and x-canal-event-hash. You can verify the webhook's authenticity by hashing the request body with your API Token and comparing it to the x-canal-event-hash value that is sent in the headers of the request.

The hash is generated using sha256:

Python

hmac.new(api_token, msg=utf_8_encoded_data, digestmod=hashlib.sha256)

Webhook Response and Data

Webhooks return object data in the same format as one would get from a GET request.

For example, subscribing to the product/create webhook sends out a request with the headers

• x-canal-app-id
• x-canal-event-hash
• x-canal-topic
• x-canal-api-version
• x-canal-webhook-id (unique per delivery, so you can use it to de-duplicate retries)

and a request body shaped like the product object that GET /products/{id} returns (see the Products API reference):

json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "shop": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "string",
    "phone": "string",
    "name": "string",
    "description": "string",
    "myshopify_domain": "string",
    "province": "string",
    "country": "string",
    "domain": "string",
    "display_domain": "string",
    "privacy_policy_url": "string",
    "terms_of_service_url": "string"
  },
  "variants": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "shop": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "string",
        "phone": "string",
        "name": "string",
        "description": "string",
        "myshopify_domain": "string",
        "province": "string",
        "country": "string",
        "domain": "string",
        "display_domain": "string",
        "privacy_policy_url": "string",
        "terms_of_service_url": "string"
      },
      "inventory_policy": "string",
      "inventory_quantity": 0,
      "inventory_item_cost": 0,
      "option1": "string",
      "option2": "string",
      "option3": "string",
      "position": 0,
      "price": "string",
      "compare_at_price": "string",
      "origin_supplier_currency": "string",
      "title": "string",
      "sku": "string",
      "upc": "string",
      "grams": 0,
      "weight": 0,
      "weight_unit": "string",
      "pause_selling": true,
      "origin_supplier_id": "string",
      "origin_supplier_name": "string",
      "available_for_ordering": true,
      "supplier_sku": "string",
      "is_exclusive_offer": true,
      "sup_price": "string",
      "sup_compare_at_price": "string"
    }
  ],
  "body_html": "string",
  "handle": "string",
  "image_src": "string",
  "images": [
    {
      "id": "string",
      "position": 0,
      "src": "string",
      "display_src": "string",
      "width": 0,
      "height": 0,
      "canal_variant_ids": ["string"],
      "variant_ids": ["string"],
      "origin_supplier_image_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "options": [
    {
      "name": "string",
      "position": 0,
      "values": ["string"]
    }
  ],
  "product_type": "string",
  "updated_at": "2023-03-29T18:55:40.410Z",
  "published_at": "2023-03-29T18:55:40.410Z",
  "status": "active",
  "title": "string",
  "vendor": "string",
  "tags": "string",
  "permalink": "string",
  "number_of_reviews": 0,
  "star_rating": 0,
  "product_type_category": null
}