NAV

Processing webhooks

Webhooks are a way to get notified about events in an Ecwid store. So they shouldn’t be used as actionable items. See processing flow examples below.

product.updated webhook processing flow example:

  • Receive a webhook from Ecwid
  • Respond with 200OK HTTP status
  • Parse the request information: identify productId from entityId, make sure the eventType is correct and get storeId value
  • Get up-to-date information about the product from Ecwid via the Ecwid REST API
  • Update your local database with latest stock quantity of that product

order.updated webhook processing flow example:

  • Receive a webhook from Ecwid
  • Respond with 200OK HTTP status
  • Parse the request information: identify orderNumber from entityId, make sure the eventType is correct and get storeId value, check if newPaymentStatus value is “PAID”
  • Get order details from Ecwid via the Ecwid REST API
  • Send order details to a fulfillment center
  • Set order fulfillment status as “PROCESSING” via the Ecwid REST API

See also the webhooks best practices on webhooks security and processing examples.

Responding to webhooks

When a webhook is sent to your URL, your app must return a 200 OK HTTP status code in reply to a webhook. This acknowledges Ecwid that you received the webhook.

Any other response (e.g. 3xx), will indicate that the webhook is not received. In this case, we will re-send a webhook every 15 minutes for 48 hours until the time is out or the resource responds with 200OK HTTP response code. Once the 48 hour limit is reached, the webhook will be removed from the queue and will not be sent again.

Troubleshooting webhooks

Q: Webhooks to my endpoint are not delivered. Why?

There are several factors that can prevent you from getting webhooks from Ecwid.

Webhooks are added to an existing application

If you registered your app without webhooks functionality and added it later on, please make sure to reinstall the app for the changes to apply faster in Ecwid.

Application is not installed

When you are expecting a webhook from Ecwid after a certain event, please make sure that you have a registered app that has all webhook details specified. More details

Application is missing the right webhook events

Webhooks in Ecwid are sent to an endpoint of an application only when event occurs and the application is set up for those webhook event types. Make sure that you specified webhook event types that you want to receive when setting up webhooks. More details

Application is missing access scopes

Webhooks also depend not only on the event types specified for them, but also for access scopes that your application has. For example, if you want to receive webhooks about new orders, then your app must request read_orders access scope from a store.

Your endpoint is not responding to requests with 200 OK status

When an event occurs, Ecwid will immediately try to send a webhook to your endpoint. However, if it fails to respond with 200OK response status or it has errors in the response (from PHP code, for example). Ecwid will not be able to deliver this webhook to your endpoint, because it failed to accept it.

This case also includes situations when your endpoint is performing redirects to other pages. In that case, it responds with 301 HTTP code, thus the webhook isn’t delivered properly.

Try sending a dummy POST request to your webhooks URL and see if it accepts the request correctly with 200OK HTTP status code. Postman is great for testing the requests.

Ecwid can’t access your endpoint

When setting up webhooks, make sure that your endpoint is publicly accessible by any resource (no local servers, etc.). This way, Ecwid services can successfully send and deliver POST requests to your endpoint.

If you made sure that all of the above steps are not concerning your case, please contact us and we will help you.

Q: I receive webhooks for events that already happened. Why?

When your application isn’t sending 200OK HTTP response back to Ecwid, the webhook event counts by Ecwid as not delivered. Such webhooks are sent again to the application URL according to the scheme described in Responding to webhooks.

Hence, if your app somehow got the webhook the first time, it will receive more of the same webhooks until Ecwid receives back the 200OK response from your app or the 48-hour timeout is over.

So please make sure that your webhooks endpoint always respods with 200OK HTTP response upon successfully receiving the webhook from Ecwid.

Q: I receive webhooks with a delay. Why?

Webhooks in Ecwid are sent out to many applications every minute. We have several servers processing the delivery of webhook requests.

When there are too many events that need to be processed, a queue is created to deliver those requests to their respective URLs. Also, sometimes the application URLs are not responding in a proper way, so we perform retries to make sure we deliver the webhooks.

All these factors can influence on when your app is going to get the webhook. So it may be delivered with a delay, which size depends on the load of our servers.