Merchant API: webhooks
About this article
This article explains how to manage webhooks via the ChannelEngine Merchant API. Learn how to create, retrieve, update, and delete webhooks.
Table of contents
Introduction
A webhook is an automatic message from ChannelEngine to a callback URL you choose. ChannelEngine sends it each time a certain event happens, e.g.: when a new order is created. Your system can then fetch the changed data right away instead of polling ChannelEngine on a schedule.
The Merchant API lets you manage webhooks from your own system. You can, however, manage webhooks in the ChannelEngine web application at Settings, Webhooks. See ChannelEngine: webhooks for details.
Overview
Refer to the flowchart below to visualize how a webhook is created and how ChannelEngine calls your system when an event happens.
Requirements
- A Merchant API key. Send it in the
apikeyquery parameter with every request. Find your Merchant API key at Settings, Merchant API keys. - A callback URL that is reachable from the internet over HTTPS.
- An endpoint behind that URL that accepts the request type you choose (
GETorPOST) and the query parameters ChannelEngine adds (see The callback request).
GET https://<your-tenant>.channelengine.net/api/v2/webhooks?apikey=your-merchant-api-keyWebhook fields
The same fields describe a webhook everywhere in the Merchant API: in the response of GET /v2/webhooks and in the request body of POST /v2/webhooks and PUT /v2/webhooks.
Webhook payload fields
| Field | Type | Required on create | Description |
Name |
string | Yes | The unique name of the webhook. Maximum 128 characters. You use this name to update and delete the webhook later. |
Url |
string | Yes | The callback URL ChannelEngine calls, for example https://test-store.com/callback. Maximum 1,028 characters. Enter only the base address; ChannelEngine adds the query parameters itself. |
IsActive |
boolean | No | Whether the webhook sends callbacks. Set to true to start sending callbacks. If you omit it on create, the webhook is created inactive. |
RequestType |
enum | No | The HTTP method ChannelEngine uses for the callback: GET or POST. The default is GET. |
Events |
array of enum | Yes | One or more events the webhook reacts to. See Events. |
Events
You can subscribe to the following events.
Webhook events
| API value | Event in ChannelEngine | Triggered when |
ORDERS_CREATE |
Orders create | An order is created. |
ORDERS_CHANGE |
Orders change | An order is updated in any field other than the status. |
PRODUCTS_CHANGE |
Products change | There is a change in your product feed. |
BUNDLE_PRODUCTS_CHANGE |
Product bundles change | A product bundle is created or updated. |
RETURNS_CHANGE |
Returns change | A return is created or updated. |
SHIPMENTS_CHANGE |
Shipments change | A shipment is created, or a cancellation is created. |
NOTIFICATIONS_CREATE |
Notifications create | ChannelEngine pushes a new notification. |
ORDERS_CHANGE does not trigger when only the order status changes.
Available API endpoints
A webhook has a unique name, a callback URL, a request type, an active flag, and one or more events it reacts to. The Merchant API exposes four endpoints to manage them.
-
Retrieve webhooks:
GET /v2/webhooks
Use this endpoint to retrieve all webhooks in your ChannelEngine tenant. -
Create a webhook:
POST /v2/webhooks
Use this endpoint to create a new webhook. If a deleted webhook with the same name exists, ChannelEngine updates and restores that webhook instead. -
Update a webhook:
PUT /v2/webhooks
Use this endpoint to change an existing webhook. ChannelEngine identifies the webhook by itsName. -
Delete a webhook:
DELETE /v2/webhooks/{webhookName}
Use this endpoint to delete a webhook by its name.
Retrieve webhooks
Call GET /v2/webhooks to list every webhook in your account. The endpoint takes no parameters. Each item in Content contains the webhook fields.
Response
{
"Content": [
{
"Name": "order-sync",
"Url": "https://test-store.com/callback",
"IsActive": true,
"RequestType": "GET",
"Events": [
"ORDERS_CREATE",
"ORDERS_CHANGE"
]
}
],
"Count": 1,
"TotalCount": 1,
"ItemsPerPage": 100,
"StatusCode": 200,
"RequestId": "…",
"LogId": "…",
"Success": true,
"Message": null,
"ExceptionType": null,
"ValidationErrors": null
}Create a webhook
Call POST /v2/webhooks with a JSON body containing the webhook fields. Name, Url, and Events are required.
Request body
{
"Name": "order-sync",
"Url": "https://test-store.com/callback",
"IsActive": true,
"RequestType": "GET",
"Events": [
"ORDERS_CREATE"
]
}Response
On success, ChannelEngine returns HTTP 201 Created with a standard ApiResponse body.
{
"StatusCode": 201,
"RequestId": "…",
"LogId": "…",
"Success": true,
"Message": null,
"ExceptionType": null,
"ValidationErrors": null
}In the example above, every time a new order is imported to ChannelEngine from one of your connected channels, you are notified of a new order that you can import to your system. When notified, call GET /v2/orders/new.
Webhook creation response status codes
| Status | Meaning |
201 Created |
The webhook was created, or a deleted webhook with the same name was updated and restored. |
400 Bad Request |
A required field is missing or invalid. Check ValidationErrors in the response. |
409 Conflict |
An active webhook with this Name already exists. Use PUT /v2/webhooks to change it, or choose another name. |
Update a webhook
Call PUT /v2/webhooks with the same body as POST /v2/webhooks. ChannelEngine finds the webhook by Name and replaces its settings with the values you send, so include every field you want to keep. Use this endpoint to pause a webhook ("IsActive": false), change its URL, or add or remove events.
Request body
{
"Name": "order-sync",
"Url": "https://test-store.com/callback",
"IsActive": false,
"RequestType": "POST",
"Events": [
"ORDERS_CREATE",
"ORDERS_CHANGE"
]
}Update webhook response status codes
| Status | Meaning |
200 OK |
The webhook was updated. |
400 Bad Request |
A required field is missing or invalid. Check ValidationErrors in the response. |
404 Not Found |
No webhook with this Name exists. Create it with POST /v2/webhooks. |
Delete a webhook
Call DELETE /v2/webhooks/{webhookName}, where webhookName is the unique name of the webhook. Deactivate the webhook with PUT /v2/webhooks before you delete it, so your system stops receiving callbacks first.
DELETE /v2/webhooks/order-syncDelete webhook response status codes
| Status | Meaning |
200 OK |
The webhook was deleted. |
404 Not Found |
No webhook with this name exists. |
POST /v2/webhooks with the same Name, ChannelEngine restores the deleted webhook with the new settings instead of creating a new one.
The callback request
When a selected event happens, ChannelEngine calls your Url with the request type you chose and adds three query parameters.
https://test-store.com/callback?type=orders&tenant=test-company&updatedSince=1640172185| Parameter | Description |
type |
The kind of data that changed, for example orders. |
tenant |
The name of your ChannelEngine tenant. Use it if you have several tenants. |
updatedSince |
A Unix timestamp (seconds). Use it as the starting point when you fetch the changed data from the Merchant API. |
The callback tells you that something changed; it does not carry the changed data itself. On receipt, fetch the data with the matching Merchant API endpoint, for example, GET /v2/orders/new for new orders.
Common issues
| What you see | Likely cause and fix |
400 Bad Request on create or update |
Name, Url, or Events is missing, or a value is out of range. Check ValidationErrors in the response. |
409 Conflict on create |
An active webhook with this Name already exists. Select another name. |
404 Not Found on update or delete |
The Name does not match an existing webhook. Names are case-sensitive. Retrieve the list with GET /v2/webhooks and copy the exact name. |
| The webhook exists but your system receives nothing |
IsActive is false. Set it to true with PUT /v2/webhooks, and check that the event you expect is in Events. |
| A deleted webhook was restored | You called POST /v2/webhooks with the name of a deleted webhook. ChannelEngine restores it by design. Use a different name if you want a separate webhook. |
| Your endpoint rejects the callback | Your endpoint must accept the RequestType of the webhook and the type, tenant, and updatedSince query parameters. |
| You need to secure the callback | The API has no authentication fields for webhooks. Add a header or query string parameter in the ChannelEngine web application at Settings, Webhooks. |
| A callback did not arrive | Delivery is not guaranteed. Poll the Merchant API on a schedule as a fallback, and check GET /v2/notifications for webhook failure notifications. |
Next steps
- ChannelEngine: webhooks: manage webhooks in the web application and add authentication.
-
Merchant API: orders: fetch new and changed orders after an
ORDERS_CREATEorORDERS_CHANGEcallback. - Merchant API: notifications: retrieve webhook failure notifications.
Comments
0 comments
Article is closed for comments.