ChannelEngine: webhooks
About this article
This article describes how to add and configure webhooks via the ChannelEngine web application, and how to fix common issues with webhooks.
Table of contents
Manage webhooks via the Merchant API
Introduction
A webhook is an automatic message from ChannelEngine to a URL you choose (your callback URL). ChannelEngine sends it each time a specific event happens, e.g.: when a new order is created. Webhooks notify your system so that you know when to retrieve the relevant data from ChannelEngine, instead of continuously polling ChannelEngine for changes.
You can access webhooks at Settings, Webhooks.
Overview
The overview lists all webhooks in your tenant.
- ID - the unique identifier of the webhook in your tenant.
- Active - shows whether the webhook is active and sending messages.
- Name - the name you chose for the webhook. E.g.: product-sync.
-
Request type - the HTTP method ChannelEngine uses to call your URL:
GETorPOST. - URL - your callback URL.
Use the search bar to find a webhook by name. Click Add to add a webhook. Click the eye icon to edit the webhook.
Add a webhook
To add a webhook via the ChannelEngine web application:
- From the sidebar menu, go to Settings, Webhooks.
-
Click Add.
Add a webhook page - Add a Name to identify your webhook. E.g.: order-sync.
- Add your callback URL. Enter only the base address. ChannelEngine adds the required parameters itself. Below you can find examples of the required input and of the resulting URL:
- Example of input - https://test-store.com/callback
- Example of result - https://test-store.com/callback?type=orders&tenant=test-company&updatedSince=1640172185
- Select a Request type:
GETorPOST. Make sure your endpoint accepts the method you choose. - Select the event(s) that the webhook should react to. See Events to learn what each event does. It is best to create a separate webhook for each event, e.g.: one for orders and one for returns. You can then pause or delete one webhook without affecting the others.
- Optionally, to apply a security layer to your webhooks, select an Authentication type: header or query string parameters.
- If you chose an authentication type, add the Authentication key parameter and the Authentication value parameter. The key and value are sent with every call, so your system can verify that the call comes from ChannelEngine.
- When you are done, toggle Active on at the top of the page and click Save.
Events
Each webhook listens to one or more events.
| Event | Triggered when |
| Orders create | An order is created. E.g.: a customer buys a product on Amazon. ChannelEngine imports the order with the status New. |
| Orders change | An order is updated in any field other than the status. E.g.: financial data is added to the order's extra data after the order was imported. |
| Products change | There is a change in your product feed. E.g.: you updated the title of a product in the feed. |
| Product bundles change | A product bundle is created or updated. E.g.: you add a new component to an existing bundle. |
| Returns change | A return is created or updated. E.g.: a customer registers a return on a marketplace. |
| Shipments change | A shipment is created, or a cancellation is created. E.g.: you have zero stock and you cancel the order. |
| Notifications create | ChannelEngine pushes a new notification. E.g.: an order remains in the status New for too long, and ChannelEngine notifies you about it. |
Update a webhook
To update a webhook:
- In Settings, Webhooks, click the eye icon next to the webhook you want to edit.
- Change any fields that you previously filled out when creating the webhook.
- Click Save.
Delete a webhook
To delete a webhook, deactivate it first.
- In Settings, Webhooks, click the eye icon next to the webhook you want to delete.
- Toggle Active off and click Save. The webhook stops sending messages.
- Once deactivated, delete the webhook via the
DELETE /v2/webhooks/{webhookName}endpoint.
Once the webhook is deleted, your system no longer receives messages for it. Make sure you no longer rely on it.
Manage webhooks via the Merchant API
If you prefer to manage webhooks from your own system, use the Merchant API. Use the /v2/webhooks resource with the appropriate method: GET to retrieve all webhooks, POST to create a webhook, PUT to update one, and DELETE /v2/webhooks/{webhookName} to delete a webhook.
For the request format, fields, examples, and error codes, see Merchant API: webhooks.
Common issues
| Issue | Likely cause |
| The webhook is saved, but your system receives nothing | A new webhook is inactive. Toggle Active on and click Save. Then, check that the event you expect is selected. |
| You cannot delete a webhook | Deactivate the webhook first: toggle Active off and click Save. Then delete the webhook via the Merchant API. |
| ChannelEngine cannot reach your endpoint | Your URL must be reachable from the internet. An address on a local or private network does not work. Also check that a firewall or security setting does not block the call. |
| Your endpoint rejects the call | Check that your endpoint accepts the request type of the webhook, GET or POST. If you use authentication, check that the type, key, and value match what your endpoint expects. |
| Your endpoint receives unexpected parameters | ChannelEngine adds type, tenant, and updatedSince to your URL. Enter only the base address in the URL field, and make sure your endpoint accepts these parameters. |
| A message did not arrive | Webhook delivery is not guaranteed, e.g.: during a network issue. Make sure your system can also fetch the latest data via the Merchant API. |
Comments
0 comments
Article is closed for comments.