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
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 fields — These 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
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 fields — These 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
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 fields — These 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
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 fields — These 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
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 fields — These 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
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 fields — These 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
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 fields — These 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
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 fields — These 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.