Getting Started with Webhooks
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:
- A configuration - This tells us where to send topics.
- A topic - This tells us what to send.
- 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. | |
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. | |
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. | |
product.inventoryChanged | Buyers | The inventory quantity of a products variant is updated by the Seller. | Syncing inventory levels rapidly to avoid over selling. |
Not seeing what you're looking for? Please reach out to support and let them know what you are looking for.
Getting Started
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:
- 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.
- A list of topics you want your endpoint to notified of.
- [Optional] A rate limit that tells us how many requests a second your endpoint can handle.
- [Optional] A burst limit that tells us how many requests your endpoint can handle simultaneously.
- 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.
- 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:
- Your target URL information.
- The state of your webhook. This is essentially whether your webhook configuration is active.
- The ability to add more webhook configurations.
- The topics you've subscribed to.
- The ability to edit your webhooks configuration information.
- The health of your webhook. This can be either HEALTHY or FAILED.
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:
- The target URL of your webhook.
- The topics associated with this webhook.
- The rate limit of your webhook.
- The burst limit of your webhook.
- The ability to add new secrets
- The expiry date of existing secrets.
