Getting Started with Webhooks
Updated
by Jason
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
We're actively working on expanding the list of available webhook topics as quickly as we can. The 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? You can request additional webhook topics using this form.
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.
- 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.
- [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.
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 topics you've subscribed to.
- 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.
- 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!
- The ability to edit your webhooks configuration information.
- 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:
- The target URL of your webhook.
- The topics associated with this webhook.
- 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!
- The ability to add new secrets.New secrets are active immediately! Please refer to this guide to learn more about how secrets work.
- The rate limit of your webhook.
- The burst limit of your webhook.
