Webhooks

Enable and configure webhooks to get notified about events in the system.

The Webhooks section allows you to manage available webhooks that you can connect to other systems you use in your company.

Webhooks is a convenient tool that allows you to subscribe to certain events that are happening in the Emporix Commerce Engine to get instant information about them. For example, you might want to subscribe to all instances when an order is created in the system and send a message about it to your external order management application for further processing.

Configuring webhook service

To receive notifications about events happening in the system, firstly configure the webhook service according to your needs. To choose the relevant strategy, follow these steps:

1. Go to Administration -> Webhooks.

2. Select one of the available strategies.
3. Depending on the selected option, you might be asked to provide more details to enable the notifications. Confirm with Active.

Webhook strategies

Emporix offers the following strategies you can choose for the webhook event gateway:

• Shared account - Svix
• Licensed account - Svix
• Other - HTTP

You can have only one strategy active at a time.

Shared account - SVIX strategy

The default solution to handle webhook events that comes with Commerce Engine is Svix-shared strategy. You can use this strategy out-of-the-box up to the set monthly limit.

Svix Dashboard

With Svix-shared webhook strategy, you get access to Svix dashboard. This is the place to connect the webhooks to specific endpoints.

1. In Administration -> Webhooks, choose Open Svix Dashboard. You're redirected to Svix.

2. Go to Endpoints and choose Add endpoint.

   • In Endpoint URL, provide a URL of the system you want to connect the webhooks to.

   • Choose the event types of your interest and choose Create to start receiving notifications.

Now, in Svix Dashboard, you can see all the events of the types that you have subscribed to. You are able to check the payload details of each particular event message sent to the external system. You can also check the schema of a particular event type under the Event catalog.

Viewing your webhook usage

With the Svix-shared strategy, the maximum number of events per tenant is limited to 5000/month. The limit resets on the first day of each month. After you exceed the set limit, the requests do not get sent. For further information about the limits, please contact the Sales department at [e-mail].

You can keep the webhooks usage under control by checking the usage statistics.

In Administration -> Webhooks, you can see your current monthly usage. By choosing the Webhook usage, you get a detailed overview of the webhooks usage in a particular period.

Licensed account - SVIX strategy

Choose the Svix strategy if you need more flexibility and want to connect your independent Svix subscription to Commerce Engine system. To activate this strategy, provide an API key that you get directly from Svix. With the Svix strategy, the monthly webhook traffic limit depends on your own Svix plan.

Other - HTTP strategy

This strategy allows you to receive webhook events notifications directly to the provided URL. When selecting this webhook strategy, provide a destination URL to consume the requests.

Optionally, you can secure HTTP communication with HMAC secret. The HMAC (keyed-Hash Message Authentication Code) security layer verifies if the checksum of data that came to the destination point is correct. HMAC is a type of authentication technique that uses a hash function and a secret key. You can use it to sign a request with a shared secret.

For more information on how to secure the requests with HMAC encryption, see HTTP Webhook Strategy - HMAC Configuration.

With Custom Headers, you can define a list of headers which are attached to the API request sent through the webhooks. For example, use custom headers to provide the following:

• authentication and authorization measures: API keys, bearer tokens, or other security tokens

• context information: some additional information about the context of a request, for example the request origin, the response preferred language, or user-defined preferences

Moreover, each HTTP request has emporix-event-publish-time header attached which contains timestamp in RFC3339 UTC "Zulu" format and provides information about the time at which the message was published. As an addition to the main destination URL, you can define more destination URLs to receive webhook notifications for particular events.

For example, you might specify a different URL to receive notifications about newly created orders and a different URL for notifications about price lists updated in CE.

To define event-specific destination URL, select the event from the list and choose Edit icon:

Subscribing to webhook events

Apart from choosing the webhook strategy that is right for you, decide which specific events you'd like to listen to.

1. In Administration -> Webhooks, expand the service of your interest to see the list of available events. Turn on the slide under Status column to switch the webhook on.

2. Go to edit mode by choosing the Edit icon.

1. Select the attributes you'd like to see in the webhook payload message. Confirm with Update subscription.

Learn about the index.item-updated event's specific behavior\

The index.item-updated webhook event is emitted whenever there is a change on an item in the system - the index is updated with the new information. For the event to be triggered, a product must have at least one defined price, as it is the price that determines products indexing on a specific site. Bear in mind all the events are site-specific, which means that they are linked to activities happening on particular sites. The prices are also site-specific, and a single price can be associated with multiple sites. The number of events triggered in the system depends on the number of sites assigned to a specific product’s prices, with one event emitted per each site.

Example:

productid	price with associated sites	number of emitted events	sites the event was emitted to
123	$10 - site A, B	2	A, B
234	$10 - site A, $15- siteA, B, C`	3	A, B, C
345	no price	0	none

A product 123 has one assigned price $10, associated with two sites A and B. When you update the product 123, the number of emitted index.item-updated events is 2 as there are two sites associated with the product price. A product 234 has two assigned prices: $10 associated with site A and $15 associated with site A, B, and C. So when you update the product 234, the index.item-updated event runs 3 times, as there are three sites affected.

• A product 123 has one assigned price of $10, associated with two sites A and B. When you update the product 123, the number of emitted index.item-updated events is 2 as there are two sites associated with the product price.

• A product 234 has two assigned prices: $10 associated with site A and $15 associated with site A, B, and C. So when you update the product 234, the index.item-updated event runs 3 times, as there are three sites affected.

• A product 345 has no defined price. So when you update the 345 product, the index.item-updated is not emitted as no site is associated with the product.

For more information on Webhooks, see the following documentation:

• System Management guide - Webhook Event Publishing and HTTP Webhook Strategy - HMAC Configuration
• API Tutorial - Webhook Service Tutorials
• Example integration:

  • HTTP Webhook Strategy - Integration with Azure Service Bus
  • HTTP Webhook Strategy - Integration with Amazon Simple Queue Service (SQS)