Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhooks Tutorial

The Emporix Webhook Event publishing works in the following way:

  1. When an event takes place and you subscribed to receiving notifications about this event, a message is sent to the Webhook Service.

  2. The Webhook Service forwards the message to the Event Gateway.

  3. The Event Gateway matches the event to your configured endpoints. For the HTTP strategy with multiple webhook targets defined, optional JsonPath filters are evaluated against the event payload.

For example, if you create a catalog in the Emporix environment, a notification is sent to the Webhook Service. The service passes the message to the Event Gateway. If you configured an endpoint for catalog creation beforehand, you receive the notification that a new catalog has been created.

For the HTTP strategy with multiple webhook targets, you can store multiple eventsConfiguration entries for the same event type.

How to configure webhook notifications

At any time, a tenant can have only one webhook configuration of each type: svix, svix_shared, and http. To switch strategy or change provider settings, update or delete the existing configuration of that type before creating a new one.

To receive notifications from Emporix API services, you need to subscribe to specific events by following the process below:

By default, the maximum number of events per tenant is limited to 5000/month. The limit resets on the first day of each month. If you want to publish more events, contact Emporix Support.

Retrieve all subscriptions

Before you subscribe to events, you need to check for any active subscriptions by sending a request to the Retrieving all subscriptions endpoint.

If the subscription to the event of your choice already exists and you want to update it, note down the metadata.version value. You will need it to call the Subscribing and unsubscribing from events endpoint further in the tutorial.

If there is no prior subscription to the event of your choice, the metadata.version is empty. It is automatically set to 1 when you send a request to the Subscribing and unsubscribing from events endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

Subscribe to events

To receive notifications about events, for example creating or updating a catalog in the Catalog Service, you need to subscribe to them by using the Webhook Service.

To subscribe to an event, you need to send a request to the Subscribing and unsubscribing from events endpoint.

In this example, you will subscribe to the following events: catalog.created and catalog.updated.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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 - sites A, B

2

A, B

234

$10 - site A, $15 - sites A, B, C

3

A, B, C

345

no price

0

none

  • 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.

Subscribe to custom entity events

You can subscribe to custom entity events the same way as other event types by calling the Subscribing and unsubscribing from events endpoint:

  • schema.custom-instance-created

  • schema.custom-instance-updated

  • schema.custom-instance-deleted

With the HTTP strategy, pair the subscription with an optional JsonPath filter on an endpoint (for example $[?(@.type == 'contract')]) when you only want specific custom entity types delivered. If no filter is configured, all events of the subscribed custom-instance type are candidates for delivery. See How to configure multiple webhook targets (HTTP strategy).

Connect to the Event Gateway

You need to have access to the Event Gateway to connect the tenant with their consumer application.

When you subscribe to events, you will receive an email with an automatically generated link to the application portal.

To generate the login link with the authentication token needed to connect a tenant to their consumer application portal, you need to send a request to the Retrieving a dashboard access URL endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

You can use your Emporix tenant ID as application ID in Svix.

Configure your endpoints

To receive notifications about the events you subscribed to in Subscribe to events, configure endpoints that relate to those events.

  • Svix strategies – On the Event Gateway, configure endpoints that relate to those events. To configure endpoints by using the APIs, check out the "Add webhook endpoints/Using the API" section in the official Svix documentation.

  • HTTP strategy – Configure a global destination URL and optional per-event eventsConfiguration entries through the Webhook Service config API, as described in How to configure multiple webhook targets (HTTP strategy).

How to configure multiple webhook targets (HTTP strategy)

Defining multiple webhook targets lets you register several HTTP targets for the same eventType. Each entry in eventsConfiguration can define its own destinationUrl, secretKey, headers, optional Jayway JsonPath filter, excludedFields, optional name (max 255 characters), and active flag.

JsonPath filter structure and validation

When you create a filter, the JsonPath expression must match the payload structure of the configured eventType. Use the corresponding schema under Webhook - Events to choose field paths. The API validates JsonPath syntax only; it does not check paths against the event schema.

Rule
Details

Field

filter (string) on an eventsConfiguration entry

Form

Jayway JsonPath predicate, typically $[?(@.<path> <op> <value>)]

Evaluation

Against the event payload

Empty / omitted

Matches every event of the given eventType

Invalid expression

Rejected with HTTP 400 and not stored

Inactive entry (active: false)

Skipped without filter evaluation, delivery, or retries

Examples:

  • Match by status – $[?(@.status == 'DECLINED')]

  • Nested path – $[?(@.total.amount > 100)] or $[?(@.status.value == 'DECLINED')]

  • Custom entity type – $[?(@.type == 'contract')]

Related validation rules:

  • Entry id is server-generated. Omit id on create (POST or PATCH create-entry); client-supplied IDs are rejected with 400.

  • On update (PUT), known IDs must refer to existing entries; unknown IDs are rejected with 400. IDs are immutable once assigned. Legacy payloads without entry IDs are still accepted; the server assigns IDs to id-less entries.

  • Duplicate entry IDs are rejected with 400.

  • Omitting excludedFields or setting it to null inherits subscription exclusions; [] means no exclusions for that target.

  • Create a new entry with UPSERT on /configuration/http/eventsConfigurationEntry (no id segment). REMOVE is not supported on that path.

  • Prefer /configuration/http/eventsConfigurationEntry/{entryId} (and field subpaths for destinationUrl, secretKey, headers, filter, excludedFields, name, and active) to address an existing entry.

  • Legacy PATCH paths by {eventType} remain supported when at most one entry exists for that type and return 409 when multiple entries exist.

Configure multiple targets for one event type

Use this pattern when one eventType needs to reach more than one HTTP destination — for example, send declined quotes to a CRM and all quote updates to analytics. Call the Updating a single webhook config endpoint with multiple eventsConfiguration entries that share the same eventType.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

After the update, retrieve the config with the Retrieving a webhook config endpoint. The response assigns a server-generated id to each entry and returns secretKeyExists instead of secretKey:

Filter custom entity events by type

Use a JsonPath filter when you subscribe to custom entity events but only want specific entity types delivered — for example, only contract updates. Call the Updating a single webhook config endpoint and set filter on the matching eventsConfiguration entry.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

With this setup, only schema.custom-instance-updated payloads where type is contract match the endpoint filter. Other custom entity types are not candidates for this entry.

Create an eventsConfiguration entry

Add a new HTTP target without replacing the full config. Call the Partially updating a webhook config endpoint with UPSERT on /configuration/http/eventsConfigurationEntry. Do not send id in the body — the server generates it.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

Update a filter by entry id

Change the JsonPath filter on an existing target without rewriting the whole eventsConfiguration list. Call the Partially updating a webhook config endpoint and address the entry with /configuration/http/eventsConfigurationEntry/{entryId}/filter.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

Deactivate a single target

Temporarily stop deliveries to one HTTP target without removing it. Call the Partially updating a webhook config endpoint with UPSERT on /configuration/http/eventsConfigurationEntry/{entryId}/active and value false. Events for a deactivated target are dropped without filter evaluation, delivery, or retries; other targets are not affected. Set the value back to true to resume deliveries.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference
PreviousWebhook Service
NextAPI Reference

Last updated

Was this helpful?