We list important notes about listening for specific events here. For general notes on Event records and their fields review our "Event Driven Webhooks — Start Here" article.

In this article we call out specific Event Types that can cause two separate events to be sent. We also define significant fields and notes we think will help when processing webhooks for these events.

Best Practice for Processing a Webhook

When processing webhooks be sure to filter events so that you only process the relevant ones. This includes the following important checks:

  • Check the signature to ensure it's sent from EvolutionX. A webhook can include a security key in the header to bypass a firewall but do not rely on IP address to whitelist webhooks for processing.

  • Check the source_user_type and other fields to determine if the event should be processed. For example you might want to process order.created if the order was created in the storefront but not if it was created by the API or Admin. In this case you should only process the event if the source_user_type = "storefront"

  • Idempotent check to prevent processing an event multiple times. An event can fire a webhook at least once. To prevent processing the same event multiple times you can store and check the event_id before processing a webhook. Keeping a list of processed event IDs for 1 day would prevent processing them twice.

  • Avoid setting the webhook to listen to events which cause duplication. Some actions in EvolutionX can generate two events and listening to both will mean two events are being seen and processed instead of one. An example is user.updated, user.subscribed, user.unsubscribed. If a user changes the subscribe status it will cause both a user.updated and user.subscribed (or user.unsubscribed) event. In this case two webhooks will fire for the one action. It is recommended that your webhook only listens to user.updated OR user.subscribed & user.usubscribed but not all three.

  • Include the object record if needed. A webhook always sends event specific information but you can also include the API record with the event details if needed. This can save you making a GET request for the record. If you don't need the full object record you can leave this off and you will still receive the Event Data fields which may be enough for your use case. Note that the record included is not guaranteed to be the record at the time of the event but the latest version of the record at the time the webhook was sent.

Logging and Retry Handling

Event webhooks sent will listen for a 200 response. If another response is provided then up to three attempts will be made, each 15min apart, before it gives up.

Webhook Events

Each webhook that is sent will record an Event of it's own. The event payload includes information about which EvolutionX event triggered it. Connected with that webhook event is also all request logs related to each attempt. We record the request to the third party server and the response and keep that for 15 days. After that only the attempt request header details, and not the request/response json, will be viewable for up to 60 days.

Filter for Webhook Events or Webhook Requests

In the webhook list view you can use the menu on the right of any webhook record to see a filtered list of webhook events or webhook requests related to that webhook.

Order Records

Order API docs

Orders in EvolutionX are created when an order is placed with a successful payment method. This includes orders placed in the storefront, orders placed by staff in the Admin, orders added using the API and orders sent from a punch out integration.

Processing Webhooks for Orders

When listening to order webhooks you should use the source_user_type to determine if the order event is created by the storefront, API, or admin. Imports do not create events.

Event for Orders

The following apps can generate these events types:

  • order.created — Admin, API, Storefront (including Punchout). Note that an order with a credit card payment method which results in a declined purchase is not yet an order and the order.created event will not occur.

  • order.updated — Admin and API

  • Order Object fieldsThese fields are included if the "Include object record" is true in the webhook setup and are documented in the API.

Order events are linked to the following objects in the Admin. Linking these means that the event can be found when filtering by these records.

  • source_user_id — This is the user who added the order record. The Source User Type can be an API user (using an API Key), an Admin user (staff), or a storefront user who is logged in.

  • event_object_id — This is the ID of the current order record for this event.

  • data.event_data.related_to.customer — This is the customer account record for the order.

  • data.event_data.related_to.user — This is the buyer and is usually the logged in user in the storefront. If the order was placed in the admin then the buying user was selected by the Staff as they added the order.

Newsletter Guest Signup Widget

The guest newsletter widget allows for any user to add an email address which is added to the newsletter table.

Each submit of that form will generate an event type:

  • newsletter.subscribed — Storefront guest newsletter widget

The newsletter subscribed event is not linked to any store records. It does provide the includes:

  • source_user_id — This usually a guest user but if the user was logged in the requesting user ID is provided.

  • data.event_data.email — the email address submitted in the form

Customer Records

Customer API docs

Processing Webhooks for Customers

When listening to customer webhooks you should use the source_user_type to determine if the customer event is created by the storefront, API, or admin. Imports do not create events.

Events for Customer records

The following apps can generate these events types:

  • customer.created — Admin, API, Storefront

  • customer.updated — Admin and API

  • customer.deleted — Admin

  • Customer Object fieldsThese fields are included if the "Include object record" is true in the webhook setup and are documented in the API. Only the object type and ID will be provided for deleted events.

Customer events are linked to the following objects in the Admin. Linking these means that the event can be found when filtering by these records.

  • source_user_id — This is the user who added the customer record. The Source User Type can be an API user (using an API Key), an Admin user (staff), or a storefront user who is logged in.

  • event_object_id — This is the ID of the current customer account record for this event.

Address Records

Address API docs

Processing Webhooks for Addresses

When listening to address webhooks you should use the source_user_type to determine if the address event is created by the storefront, API, or admin. Imports do not create events.

Events for Address records

The following apps can generate these events types:

  • address.created — Admin, API, Storefront

  • address.updated — Admin, API, Storefront

  • address.deleted — Admin and Storefront

  • Address Object fieldsThese fields are included if the "Include object record" is true in the webhook setup and are documented in the API. Only the object type and ID will be provided for deleted events.

Address events are linked to the following objects in the Admin. Linking these means that the event can be found when filtering by these records.

  • source_user_id — This is the user who added the address record. The Source User Type can be an API user (using an API Key), an Admin user (staff), or a storefront user who is logged in.

  • event_object_id — This is the ID of the current address record for this event.

  • data.event_data.related_to.customer — This is the customer account record for the address.

User Records

User API docs

Processing Webhooks for Users

When listening to user webhooks you should use the source_user_type to determine if the user event is created by the storefront, API, or admin. Imports do not create events.

Two events can occur in some use cases. An example is user.updated, user.subscribed, user.unsubscribed. If a user changes the subscribe status it will cause both a user.updated and user.subscribed (or user.unsubscribed) event. In this case two webhooks will fire for the one action. It is recommended that your webhook only listens to user.updated OR user.subscribed & user.usubscribed but not all three.

Events for User records

The following apps can generate these events types:

  • user.created — Admin, API, Storefront

  • user.updated — Admin, API, Storefront

  • user.deleted — Admin

  • user.subscribed — Admin, Storefront

  • user.unsubscribed — Admin, Storefront

  • User Object fieldsThese fields are included if the "Include object record" is true in the webhook setup and are documented in the API. Only the object type and ID will be provided for deleted events.

User events are linked to the following objects in the Admin. Linking these means that the event can be found when filtering by these records.

  • source_user_id — This is the user who added the user record. The Source User Type can be an API user (using an API Key), an Admin user (staff), or a storefront user who is logged in.

  • event_object_id — This is the ID of the current user record for this event.

  • data.event_data.related_to.customer — This is the customer account record for the user.

Open Quote Records

Open Quotes API docs

Processing Webhooks for Open Quotes

When listening to user webhooks you should use the source_user_type to determine if the open quote event is created by the storefront or admin. Imports do not create events.

Events for Open Quote records

Note that open quotes do not record a created event in the storefront and listening to quote.sent is a good way to track a customer sending the quote request and treating it as the created event. The following apps can generate these events types:

  • quote.sent — Admin, Storefront

  • quote.created — Admin

  • quote.updated — Admin

  • Open Quote Object fieldsThese fields are included if the "Include object record" is true in the webhook setup and are documented in the API.

Open Quote events are linked to the following objects in the Admin. Linking these means that the event can be found when filtering by these records.

  • source_user_id — This is the user who added the open quote record. The Source User Type can be an API user (using an API Key), an Admin user (staff), or a storefront user who is logged in.

  • event_object_id — This is the ID of the current open quote record for this event.

  • data.event_data.related_to.customer — This is the customer account record for the open quote. If a guest user this will be a value of zero.

  • data.event_data.related_to.user — This is the buyer and is usually the logged in user in the storefront. If the open quote was created in the admin then the buying user was selected by the Staff as they added the order. If a guest user this will be a value of zero.

Catalog Containers

Catalog Containers API docs

Processing Webhooks for Catalog Containers

When listening to user webhooks you should use the source_user_type to determine if the Catalog Containers event is created by the admin or API. Imports do not create events.

Events for Catalog Containers records

The following apps can generate these events types:

  • container.created — Admin, API

  • container.updated — Admin, API

  • container.deleted — Admin, API

  • Catalog Container Object fieldsThese fields are included if the "Include object record" is true in the webhook setup and are documented in the API. Only the object type and ID will be provided for deleted events.

Products

List All Products by ID API docs

Processing Webhooks for Product Objects

When the product object is requested the webhook object will include a list of products that match the ID. The product or item ID may appear in more than one catalog. A child product, for example, can have the same product ID in two different catalogs. To get a fully comprehensive product listing which includes categories, keywords, and many other related records, use the Viewing a Product endpoint and include the supplier ID and catalog ID.

When listening to user webhooks you should use the source_user_type to determine if the Product event was created by the admin or API. Imports do not create events.

Events for Product records

The following apps can generate these events types:

  • product.created — Admin, API

  • product.updated — Admin, API

  • product.deleted — Admin, API

  • Product Object fieldsThese fields are included if the "Include object record" is true in the webhook setup and are documented in the API. To a full product record which includes categories, keywords, and many other related records, use the Viewing a Product endpoint and include the supplier ID and catalog ID. Only the object type and ID will be provided for deleted events.

Categories

Category API docs

Processing Webhooks for Categories

Note that Category events are only created in the Admin. Imports do not create events.

Events for Category records

The following apps can generate these events types:

  • category.created — Admin

  • category.updated — Admin

  • category.deleted — Admin

  • Category Object fieldsThese fields are included if the "Include object record" is true in the webhook setup and are documented in the API. Only the object type and ID will be provided for deleted events.

Did this answer your question?