Overview
Webhooks are a tool used to automatically send data between two applications when a specific event occurs. For example, when an order is placed in one system, the webhook sends the data to another system in real-time, allowing the second application to act without manual intervention. In CommerceHub, you can set up webhooks for various predefined events. Lean how to setup webhook here.
Basic Information
In this section, you will define the key details for your webhook, including its name, the type of entity it will track, and the specific event that will trigger the webhook. Additionally, you'll configure how the webhook will communicate with the target system.
| Field | Description | Field Type |
|---|---|---|
| Name | Enter the name of the webhook. | Free Text |
| Entity Type | Select the type of entity to track (e.g., Order, Product, Customer). | Dropdown List |
| Event Type | Choose the type of event to trigger the webhook (e.g., Created, Updated, Cancelled). | Dropdown List |
| Target Type | Select how the data will be shared: REST API or Azure Queue. | Dropdown List |
| Auth Method | Choose the method of authentication (e.g., Basic Auth, OAuth). | Dropdown List |
| Custom Headers | Set custom headers by entering Key and Value pairs. | Free Text |
| Channels | Select one or more channels to receive data (e.g., App, Web, Store, MarketPlace). | Multi-Select |
Webhook Settings
This section is where you'll configure the details of the message that will be sent by the webhook. This includes the destination URL, the format in which the data will be sent, and the message template structure.
| Field | Description | Field Type |
|---|---|---|
| Destination URL | Enter the destination URL (select either HTTP or HTTPS). | Free Text Field |
| Message Format | Choose the message format: JSON or XML. | Radio Button |
| Message Template | Define the message structure based on the entity and event type. | Free Text Field |
Webhook Flags
Webhook flags are additional settings that allow you to control encryption, activation status, and notifications for the webhook. These settings provide more flexibility for your integration needs.
| Field | Description | Field Type |
|---|---|---|
| Is Encrypt | Enable encryption for the webhook. | Checkbox |
| Is Active | Activate or deactivate the webhook. | Checkbox |
| Is Firebase Notification | Specify if the webhook triggers a Firebase notification. | Checkbox |
Entity & Event Types
In eCommerce, each webhook can be associated with a specific Entity Type and corresponding Event Type. The Entity Type represents the resource or object being tracked (e.g., a customer, an order), while the Event Type refers to the specific action that triggers the webhook (e.g., an order being created, a customer being updated). The below table outlines common entity types and their associated event types:
| Entity Type | Event Type | Description |
|---|---|---|
| Company | CompanyCreated, CompanyUpdated | Triggers when a new company is created in the B2B module. Triggers when company details are updated in the B2B module. |
| Customer | CustomerCreated, CustomerUpdated, CustomerDeleted, CustomerNewsletterSubscribe, CustomerNewsletterUnsubscribe | Fires when a new customer account is created. Triggers when customer details are updated. Notifies when a customer account is deleted. Notifies when a customer subscribes to newsletters. Notifies when a customer unsubscribes from newsletters. |
| Orders | OrderCreated, OrderApproved, OrderCancelled, OrderDelivered, OrderUpdated | Triggers when a new order is created. Fires when an order is approved. Notifies when an order is canceled. Fires when an order is marked as delivered. Notifies when the details of an order are updated. |
| OrderLines | OrderLineCreated, OrderLineUpdated, OrderLineDeleted | Triggers when a new order line (individual product in an order) is created. Notifies when an individual order line is updated. Notifies when an order line is deleted. |
| Product | ProductCreated, ProductUpdated, ProductPriceUpdated | Triggers when a new product is created in the catalog. Triggers when product details are updated. Fires when the price of a product is updated. |
| Promotion | PromotionCreated, PromotionUpdated | Fires when a new promotion is created. Notifies when an existing promotion is updated. |
| Quotes | QuoteCreated, QuoteUpdated | Notifies when a new quote is created. Notifies when an existing quote is updated. |
| RMA | RMACreate, RMAReceived | Fires when a return request (RMA) is created. Notifies when a return (RMA) is received. |
| Store | StoreCreated, StoreUpdated | Triggers when a new store is created in the system. Fires when store details are updated. |
Target Types
The Target Type specifies where the webhook data is sent upon being triggered by an event. In CommerceHub, the following target types are supported:
| Target Type | Description |
|---|---|
| REST API | Sends data to a REST API endpoint. Supported HTTP methods include GET, POST, PUT, PATCH, DELETE, and more. |
| Azure Queue | Pushes messages to an Azure Queue for further processing or handling. |
Authentication Types
Webhooks can be secured with various authentication methods to ensure that data is sent securely. The available authentication types are as follows:
| Authentication Type | Description |
|---|---|
| None | No authentication is required for the webhook. |
| Basic | Requires a username and password for authentication. |
| Token | Utilizes a token for secure authentication. |
| OAuth | Authenticates using the OAuth protocol for secure access. |
Custom Headers
When configuring webhooks, you have the option to add Custom Headers. These headers provide additional metadata or information that the receiving server may require. Custom headers can be used for various purposes, such as passing authentication tokens, defining content types, or including other necessary information for the receiving application. Common use cases include:
| Header Field | Description |
|---|---|
| Key | Specifies the name of the custom header. |
| Value | Defines the value associated with the custom header. |
Additional Options
Here are some extra tools to help you manage your webhooks more efficiently:
- View Variables: Shows available variables for use in message templates. Detailed variable list can be found in this article.
- View Changelog: Displays changes made to the webhook configuration.
- Post Webhook Logs: View logs for tracking webhook activities.