Webhooks

Overview

Webhooks allow your application to to subscribe to events that occur within Canal, giving you updates whenever there is a change made by Canal or a Canal-powered Supplier. The current set of webhooks that are available for use are listed under "Webhook Topics" below.

Webhook Topics

You can currently subscribe to any of the following webhooks:

order/create: When your Storefront creates an order for a Canal-powered Supplier, Canal will send an order confirmation to your application.

order/update: When an update is made to a Canal-powered Supplier order that was created via your Storefront, Canal will send the new information to your application.

product/create: When your Storefront is approved to sell a specific product, you must first go to the Canal app and click the "Add to store" button next to the product in the Inventory tab. When this button is clicked, the webhook will send the product's data to your application so that it can be added to your Storefront.

product/update: When a Canal-powered product on your Storefront is updated by the Supplier, such as the product's price or description, Canal will use this webhook to send the new data to your application.

fulfillment/create: When a Canal Supplier creates a new fulfillment job for an order placed via your Storefront, Canal will send the data about the fulfillment to your application.

fulfillment/update: When a Supplier updates and existing fulfillment job for an order placed via your Storefront, Canal will send the update to your application.

Webhook Registration

There are two methods to register a webhook:

Method 1: Canal App

To register a new webhook:

  1. Log into your account on the Canal 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."

  1. Click on "Add webhook" and enter in the information requested.
  2. 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.storefront.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 Canal. Canal will send 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 Application ID 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:

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

Webhook Response and Data

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

For example, subscribing to the products/create webhook will send out a request with the headers

  • x-canal-app-id
  • x-canal-app-event-hash
  • x-canal-app-topic
  • x-canal-api-version

and request body

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "shop": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "myshopify_domain": "string",
    "country": "string",
    "domain": "string"
  },
  "variants": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "shop": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "myshopify_domain": "string",
        "country": "string",
        "domain": "string"
      },
      "inventory_policy": "string",
      "inventory_quantity": 0,
      "inventory_item_cost": 0,
      "option1": "string",
      "option2": "string",
      "option3": "string",
      "position": 0,
      "price": 0,
      "title": "string",
      "sku": "string",
      "grams": 0,
      "weight": 0
    }
  ],
  "body_html": "string",
  "handle": "string",
  "image_src": "string",
  "images": {},
  "options": {},
  "product_type": "string",
  "published_at": "2023-03-29T18:55:40.410Z",
  "status": "active",
  "title": "string",
  "vendor": "string",
  "origin_supplier_shop_domain": "string"
}

Updated 2 months ago

More Resources