Webhooks are a powerful automation tool. To properly use webhooks, it is important to understand when you receive them and what you can find inside.
Webhook events are triggers Ecwid uses to notify apps when something happens in the store. At its core, any webhook event consists of what was affected (entity) and how it was affected (action). So a customer.created webhook event tells you that a new customer was created in the store.
Webhook data refers to all essential details about the event sent to applications as a webhook body. Data includes timestamp, store and entity ID, and some additional details like order statuses.
When webhook events are triggered
Ecwid triggers webhooks every time this event happens in a store. Triggers work independently of the change source: Ecwid admin, storefront or checkout, REST API. In any case, changes trigger related webhooks.
For example, the order.created event triggers when a new order is created in the store including both orders placed through the checkout and orders created with REST API, the product.deleted event triggers when a product is deleted from the store both through Ecwid admin or with a REST API request.
Be careful with webhook processing. If you automate sending a product update REST API request upon receiving a product.updated webhook, you'll get into a loop of infinite product updates and webhooks.
When multiple events are triggered
When something changes in a store, the change could affect several entities. As a result, what you see as one "store event" can lead to multiple webhooks sent to an app. The most common example is a new order.
When a customer places a new order at the checkout, several things happen:
- A new order is created.
- Stock of products from the order is decreased.
- A new customer is created or an existing customer is updated.
So if an app listens for all of the order.created, product.updated, customer.created, and customer.updated, it will receive three or more webhooks from a single "store event". Make sure your application reacts to different events properly.
Data contained in webhook body
When you receive a webhook, you get some information about the event. Ecwid doesn't send full details to keep webhooks fast, but it is enough for making automation.
Webhook requests contain the following fields in the request body:
| Field | Type | Description |
|---|---|---|
| eventId | string | Unique ID for the webhook event. Useful when you receive several webhooks about the same entity in a short period. |
| eventCreated | number | UNIX timestamp when the event happened in a store. |
| storeId | number | Ecwid store ID where a webhook event happened. |
| entityId | string | ID of the entity. Can contain ID of product, order, category, invoice, etc. depending on the event type. |
| eventType | string | Webhook event happened in the store. Tells what was changed and how it was changed. Read more about supported webhook events. |
| data | array{data} | (Optional). Additional information about some webhook events. |
data
Webhook request body for events like order.created, profile.subscriptionStatusChanged, customer.created, and invoiceCreated contains additional data about the event.
| Name | Type | Description |
|---|---|---|
| orderId | string | Order ID. Available for the following events: order.created, order.updated, order.deleted, invoice.created, invoice.deleted. |
| cartId | string | Abandoned cart ID. Available for the following events: unfinished_order.created, unfinished_order.updated, unfinished_order.deleted. |
| oldPaymentStatus | string | Order payment status before changes. Available for the following events: order.updated. |
| newPaymentStatus | string | Order payment status after changes. Available for the following events: order.created, order.updated. |
| oldFulfillmentStatus | string | Order fulfillment (shipping) status before changes. Available for the following events: order.updated. |
| newFulfillmentStatus | string | Order fulfillment (shipping) status after changes. Available for the following events: order.created, order.updated. |
| oldSubscriptionName | string | Ecwid subscription plan before changes. Available for the following events: profile.subscriptionStatusChanged. |
| newSubscriptionName | string | Ecwid subscription plan after changes. Available for the following events: profile.subscriptionStatusChanged. |
| oldSubscriptionStatus | string | Application subscription status before changes. Available for the following events: application.subscriptionStatusChanged. |
| newSubscriptionStatus | string | Application subscription status after changes. Available for the following events: application.subscriptionStatusChanged. |
| customerEmail | string | Customer email. Available for the following events: customer.created, customer.updated, customer.deleted. |
Check out webhook body examples.