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 support@convictional.com

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.

Topic

Available For

Occurs When

Example Use Cases

Payload

order.fulfilled

Buyers

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

order.cancelled

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

product.selected

Buyers

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

Adding a new product to your PIM or PXM system.

Buyer Product

product.inventoryChanged

Buyers

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

Syncing inventory levels rapidly to avoid over selling.

Buyer Product

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 be publicly available, not have any authentication, and use HTTPS.
    You can only have a single webhook configuration per target URL.
  2. A list of topics you want your endpoint to notified of.
  3. 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.
  4. A secret expiry date to make sure your validation secrets don't go stale. You can add more secrets after creating your webhook.
  5. [Optional] A rate limit that tells us how many requests a second your endpoint can handle.
  6. [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!

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

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 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 expirying the existing one and adding a new secret!
  4. The ability to add new secrets.
    New secrets are active immediately! Please refer to this guide to learn more about how secrets work.
  5. The rate limit of your webhook.
  6. The burst limit of your webhook.

How did we do?

Building API Integrations

Getting Started with the Buyer API

Contact