Getting Started with Webhooks

Mitch Corish Updated by Mitch Corish

Webhooks at Convictional

The addition of webhooks were one of the most requested features by developers during 2021. It's been a ongoing effort to introduce the processes and technologies required to support this feature and we're consistently looking to expand usage. As always if you run into issues or have questions about using webhooks please reach out to

When we say 'webhook' what we really mean is a endpoint, created by you, that receives one or more different 'event notifications' (called topics) when something happens within Convictional. The goal is to make it easier for you to know about changes with less boiler plate code.

The webhook system consists of three different parts:

  1. A configuration - This tells us where to send topics.
  2. A topic - This tells us what to send.
  3. A request - This tells us if what we sent was received properly and allows us to retry sending failed requests.

Available Topics

WThe table below lists all webhook topics that are currently available. You are also able to view the list of topics in the Convictional web app when creating a new webhook configuration.


Available For

Occurs When

Example Use Cases




A fulfillment is added to an order. It does not occur when a fulfillment is updated.

Sending an email to an end customer notifying that the order has shipped.

Seller Order


Sellers & Buyers

One or more line items on an existing order are cancelled.

Notifying customers when an order is cancelled by the vendor.

Seller Order



A product is selected by a user in the Convictional web app.

Adding a new product to your PIM or PXM system.

Buyer Product



The inventory quantity of a products variant is updated by the Seller.

Syncing inventory levels rapidly to avoid over selling.

Buyer Product



A product is no longer available to you from a seller in Convictional.

Ensuring that you are not selling a product that is no longer offered by a seller

Product Deleted (ID of the product only)



A variant that is no longer available to you from a seller in Convictional.

Ensuring that you are not setting a variant of a product that is no longer offered by a seller.

Variant Deleted (ID of the variant(s) only)

Not seeing what you're looking for? Please reach out to support and let them know what you are looking for.

Getting Started

To get started you'll need a publicly available endpoint that uses HTTPS and can accept POST requests. A simple, low effort way to start consuming webhooks is to use cloud functions offered by Google Cloud, AWS or Microsoft Azure.
Refer to this guide to help you get started coding your first webhook consumer!

After logging into your Convictional account you'll be able to create, edit and monitor your webhooks from the Webhooks section in the Settings.

Creating a new configuration

To create a new webhook you'll need:

  1. A publicly available endpoint capable of consuming HTTPS POST requests.
    Target URLs must use HTTPS, be publicly available, not have any authentication.
    You can only have a single webhook configuration per target URL.
  2. A list of topics you want your endpoint to notified of.
  3. [Optional] A rate limit that tells us how many requests a second your endpoint can handle.
  4. [Optional] A burst limit that tells us how many requests your endpoint can handle simultaneously.
The default value of 0 for rate and burst limits means that there is no limit!
  1. A secret value used to attach validation headers to each webhook request sent to your endpoint.
    Please refer to this guide to learn more about how secrets work.
  2. A secret expiry date to make sure your validation secrets don't go stale. You can add more secrets after creating your webhook.

When you're ready click "Submit" to create your webhook configuration!

Viewing Existing Configurations

After you've created your webhook you'll be able to see:

  1. Your target URL information.
  2. The state of your webhook. This is essentially whether your webhook configuration is active.
A webhook enters a failed state after it has failed to accept requests for 3 days.
  1. The ability to add more webhook configurations.
  2. The topics you've subscribed to.
  3. The ability to edit your webhooks configuration information.
  4. The health of your webhook. This can be either HEALTHY or FAILED.
If a webhooks health becomes 'FAILED' we also deactivate it to prevent us from sending more requests. When it's ready to recieve requests again simply activate it here again and we'll try again!

Editing Existing Configurations

If you choose to edit an existing configuration you'll see a form similar to the 'create webhook' form:

You can edit:

  1. The target URL of your webhook.
  2. The topics associated with this webhook.
  3. The rate limit of your webhook.
  4. The burst limit of your webhook.
  5. The ability to add new secrets
New secrets are active immediately! Please refer to this guide to learn more about how secrets work.
  1. The expiry date of existing secrets.
You are not able to edit the secret value of existing secrets for security reasons. If you wish to change an existing secret we recommend expiring the existing one and adding a new secret!

How did we do?

Building API Integrations

Getting Started with the Buyer API