NAV
App details page
Open page in storefront

Webhook structure

Webhook is a POST request sent to your app URL. Its body contains several fields, like: store ID, entity ID (product ID, order number, etc.), event type and more.

Learn about getting webhook fields in Webhooks best practices

Request headers

Webhook header example

POST https://www.myapp.com/callback?eventtype=order.updated HTTP/1.1
Host: www.myapp.com
Content-Type: application/json; charset=UTF-8
Content-Length: 243
Cache-Control: no-cache
X-Ecwid-Webhook-Signature: MeV28XtFal4HCkYFvdilwckJinc6Dtp4ZWpPhm/pzd4=

Among the other headers, HTTP webhook request from Ecwid includes the X-Ecwid-Webhook-Signature header that can be used to verify the webhook.

See more details in the Webhooks security.

Custom HTTP Headers

Custom webhook headers example

POST https://www.myapp.com/callback?eventtype=order.updated HTTP/1.1
Host: www.myapp.com
Content-Type: application/json; charset=UTF-8
Content-Length: 243
Cache-Control: no-cache
X-Ecwid-Webhook-Signature: MeV28XtFal4HCkYFvdilwckJinc6Dtp4ZWpPhm/pzd4=
Custom-Webhook-Header-Name: custom webhook header value

Webhooks also allow you to specify custom headers that Ecwid will use when sending a webhook to your endpoint.

For example, if you have only one endpoint and several applications sending webhooks to that endpoint, you may want to specify a custom HTTP header to know the application this webhook was sent to.

The custom HTTP headers specified for webhooks will be added to the default list of headers Ecwid is sending.

In case if a custom webhook HTTP header is duplicating a default header, Ecwid will send both the default and custom header in a request.

To setup custom HTTP headers for your app webhooks, please contact us.

Webhook request body

Unfinished order created webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":-1, // order number of the unfinished order (for older stores)
  "eventType":"unfinished_order.created"
}

Unfinished order updated webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":-1, // order number of the unfinished order (for older stores)
  "eventType":"unfinished_order.updated"
}

Unfinished order #105 deleted webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":-1, // order number of the unfinished order (for older stores)
  "eventType":"unfinished_order.deleted"
}

Order #100 created webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":103, // this is the number of the placed order
  "eventType":"order.created",
  "data":{
    "newPaymentStatus":"PAID",
    "newFulfillmentStatus":"SHIPPED"
  }
}

Order #103 updated webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":103, // this is the number of the updated order
  "eventType":"order.updated",
  "data":{
    "oldPaymentStatus":"PAID",
    "newPaymentStatus":"PAID",
    "oldFulfillmentStatus":"PROCESSING",
    "newFulfillmentStatus":"SHIPPED"
  }
}

Order #102 deleted webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":102, // this is the number of the deleted order
  "eventType":"order.deleted"
}

Product with ID 667251253 created webhook body example

{
  "eventId":"08a78904-4c1a-0aa0-953a-2e33c56236f1",
  "eventCreated":1469429915,
  "storeId":1003, 
  "entityId":667251253, // this is the id of the created product
  "eventType":"product.created"
}

Product with ID 66722483 updated webhook body example

{
  "eventId":"08a78904-0aa0-4c1a-953a-2e33c56236f0",
  "eventCreated":1469429912,
  "storeId":1003, 
  "entityId":66722483, // this is the id of the updated product
  "eventType":"product.updated"
}

Product with ID 667251253 deleted webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1469429915,
  "storeId":1003, 
  "entityId":667251253, // this is the id of the deleted product
  "eventType":"product.deleted"
}

Category with ID 66722483 created webhook body example

{
  "eventId":"08a78904-0aa0-4c1a-953a-2e33c56236f0",
  "eventCreated":1469429912,
  "storeId":1003, 
  "entityId":66722483, 
  "eventType":"category.created"
}

Category with ID 66722483 updated webhook body example

{
  "eventId":"08a78904-0aa0-4c1a-953a-2e123c236f0",
  "eventCreated":1469429912,
  "storeId":1003, 
  "entityId":66722483, 
  "eventType":"category.updated"
}

Category with ID 66722483 deleted webhook body example

{
  "eventId":"08a78904-0aa0-4c1a-953a-2e33c562336f0",
  "eventCreated":1469429912,
  "storeId":1003, 
  "entityId":66722483, 
  "eventType":"category.deleted"
}

Application was installed webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":"1003", // this is the id of a store that installed the app
  "eventType":"application.installed"
}

Application subscription status changed webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":"1003", // this is the id of a store where app subscription status was changed
  "eventType":"application.subscriptionStatusChanged",
  "data":{
    "oldSubscriptionStatus":"TRIAL",
    "newSubscriptionStatus":"ACTIVE"
    }
}

Application was deleted webhook body example

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1234567,
  "storeId":1003,
  "entityId":"1003", // this is the id of a store that deleted the app
  "eventType":"application.uninstalled"
}

Store has switched from Business to Unlimited plan

{
  "eventId":"80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated":1494503041,
  "storeId":1421002,
  "entityId":1421002, // this is the id of a store that switched to a different Ecwid plan
  "eventType":"profile.subscriptionStatusChanged",
  "data":{
    "oldSubscriptionName":"ECWID_BUSINESS",
    "newSubscriptionName":"ECWID_UNLIMITED"
  }
}

Customer was created

{
  "eventId": "80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated": 7891234567,
  "storeId": 1003,
  "entityId": 1663830, // customer ID
  "eventType": "customer.created",
  "data": {
    "customerEmail":"user@example.com" // customer email
  }
}

Customer was updated

{
  "eventId": "80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated": 7891234567,
  "storeId": 1003,
  "entityId": 1663830, // customer ID
  "eventType": "customer.updated",
  "data": {
    "customerEmail":"user@example.com" // customer email
  }
}

Customer was deleted

{
  "eventId": "80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated": 7891234567,
  "storeId": 1003,
  "entityId": 1663830, // customer ID
  "eventType": "customer.deleted",
  "data": {
    "customerEmail":"user@example.com" // customer email
  }
}

Store information updated

{
  "eventId": "80aece08-40e8-4145-8764-6c2f0d38678",
  "eventCreated": 7891234567,
  "storeId": 1003,
  "entityId": 1003
  "eventType": "profile.updated"
}

The request body is a JSON object with the following fields:

NameTypeDescription
eventIdnumberUnique webhook ID
eventTypestringType of the occurred event.
eventCreatedtimestampUnix timestamp of the occurred event.
storeIdnumberStore ID of the store where the event occured.
entityIdnumberId of the updated entity. Can contain productId, categoryId, orderNumber, storeId depending on the eventType. Is -1 for unfinished_order.* webhook events for newer stores
data<WebhookData>Optional field. Describes changes made to an entity. Is provided for order.* and application.subscriptionStatusChanged event types.

WebhookData

NameTypeDescription
oldPaymentStatusstringPayment status of order before changes occurred
newPaymentStatusstringPayment status of order after changes occurred
oldFulfillmentStatusstringFulfillment status of order before changes occurred
newFulfillmentStatusstringFulfillment status of an order after changes occurred
oldSubscriptionNamestringPrevious Ecwid store premium plan name
newSubscriptionNamestringNew Ecwid store premium plan name
oldSubscriptionStatusstringPrevious application subscription status before changes occurred
newSubscriptionStatusstringNew application subscription status after changes occurred
customerEmailstringEmail of a customer

The eventType field is also duplicated in the request GET parameters. This allows you to filter our the webhooks you don’t want to handle.

For example, if you only need to listen to order updates, you can just reply 200 OK to every request containing products updates, e.g. https://www.myapp.com/callback?eventtype=product.updated, and avoid further processing.

Event types

  • unfinished_order.created Unfinished order is created
  • unfinished_order.updated Unfinished order is updated
  • unfinished_order.deleted Unfinished order is deleted
  • order.created New order is placed
  • order.updated Order is changed
  • order.deleted Order is deleted
  • product.created New product is created
  • product.updated Product is updated
  • product.deleted Product is deleted
  • category.created New category is created
  • category.updated Category is updated
  • category.deleted Category is deleted
  • application.installed Application is installed
  • application.uninstalled Application is deleted
  • application.subscriptionStatusChanged Application status changed
  • profile.updated Store information updated
  • profile.subscriptionStatusChanged Store premium subscription status changed
  • customer.created Customer is created
  • customer.updated Customer is updated
  • customer.deleted Customer is deleted

All order-related webhooks require read_orders access scope, all product- and category-related webhooks require read_catalog access scope, all customer-related webhooks require read_customers access scope to be requested from the store.

Webhooks’ structure FAQ

Q: What is an unfinished order and how it works?

The typical process of ordering in Ecwid store is:

  • customer adds products to cart
  • goes to the checkout pages
  • fills in shipping and billing details
  • goes to payment processor and pays for order
  • customer returns to store

An unfinished order (or abandoned cart) is created when a customer goes to payment processor or order confirmation page. In case if customer pays for their order, then it is placed among other successful orders in store sales history. However, if customer fails to make a payment and never completes the order, then it will stay as unfinished order.

There is a separate tab in Ecwid control panel > My Sales > Abandoned carts where merchants can see all those orders and their details.

unfinished_order.* webhook event types are providing timely updates about unfinished orders in Ecwid store.

Here’s how the process works in technical terms:

  • when customer goes to payment processor, unfinished_order.created webhook is sent (if customer was able to pay for an order within 1 second of that, order.created is sent instead)

  • if customer paid later for their order, Ecwid sends order.created webhook after it happens

Webhooks about unfinished orders can be a great help for applications, which goal is track cart abandonment and get back those lost sales.

Recommendations

We recommend the following workflow:

  • app recieves unfinished_order.created webhook about order A
  • app waits for order.created webhook about order A for 5-10 minutes
  • in case if there was no order.created webhook received, consider this order unfinished

After that, application can send an email to that person, following up on that unfinished order or provide some other functionality.

Q: When 'unfinished_order.deleted’ event type is sent?

When a merchant deletes an unfinished order in their Ecwid control panel, hidden field in order details becomes true. After that update unfinished_order.updated webhook is sent. So the details of this order are still available to be accessed via Ecwid API.

To completely delete an unfinished order, make a delete order request to Ecwid API. If your app is set up to receive unfinished_order.deleted webhooks, Ecwid will send that webhook to endpoint of your application.

Q: How can I know if order status was changed?

Webhooks in Ecwid have a specific field for that: data. This field provides information about changes to both payment and fulfilment status of orders.

Contents of data field also lets you know the details about old status (before the changes) and the new one (after the changes) at all times. For example, your application can send a note to your warehouse if it received a webhook about order payment status changes from Awaiting payment to Paid.

Q: How can I know the current app subscription status of a store?

Once you received application.subscriptionStatusChanged webhook, you can make a request to Application endpoint to get the current subscription status of your app in that store.

We use cookies and similar technologies to remember your preferences, measure effectiveness of our campaigns, and analyze depersonalized data to improve performance of our site. By choosing «Accept», you consent to the use of cookies.
Accept cookies Decline