LogoLogo
Build appsContact API support
Webhook automations
  • Build apps
  • Site Templates
  • API Reference
  • Changelog
Webhook automations
  • Webhook automations overview
  • Setup webhooks
    • How to process webhooks
    • Set up webhooks for your app
    • Code example for webhook handling
  • Learn Ecwid webhooks
    • List of webhook events
    • Event data in webhooks
  • Customize webhooks
    • Pass additional data through webhooks
  • Webhook flow examples
    • Export new orders
    • Sync product stock

Lightspeed® 2025

On this page
  • Step 1. Respond with status 200
  • Step 2. Parse webhook data
  • Step 3. Verify webhook signature

Was this helpful?

  1. Setup webhooks

How to process webhooks

When you get a webhook from Ecwid API, you need to let Ecwid know that your server received it, verify its identity, and parse the data inside for further automation. We refer to this process as webhook handling.

Webhooks are triggered by any changes in the store data no matter their source. For example, if you create a new order with the REST API request, you'll still receive the order.created webhook.

Step 1. Respond with status 200

Your app must send a confirmation when it receives a webhook. Otherwise, according to our resend policy, Ecwid API will retry to deliver this webhook for the next 24h.

So, the first step is to inform Ecwid about the successful webhook delivery. The app must return the HTTP 200 OK status code or one of the allowed alternatives in response to every received webhook:

Response HTTP code
Result

200, 201, 202, 204, 209

Webhook counts as delivered.

203, 208, any other 2xx or 3xx

Webhook counts as not delivered.

If something goes wrong and the webhook is not delivered, Ecwid makes several attempts to deliver it in the next 24h by the following schedule:

Attempt №
Schedule

1

15 min

2

30 min

3

45 min

4

1h

5

2h

6

3h

7

4h

8

5h

9

6h

...

...

27

24h

If your webhookUrl fails to respond in 2 weeks, webhooks for your app will be blocked.

Your app must also send the response in time. Ecwid tries to connect with your webhookUrl and waits for the response for a limited time.

If your app fails to respond in time, Ecwid calls a timeout and counts this webhook as not delivered:

Timeout in

webhookUrl connection time

3 sec

Time to receive a response from webhookUrl

10 sec

Step 2. Parse webhook data

After confirming webhook delivery, the app must decode and parse the webhook body and verify that it comes from Ecwid.

Code example for webhook body decoding and parsing:

$decodedBody = json_decode($requestBody, true);

$eventId = $decodedBody['eventId'];
$eventCreated = $decodedBody['eventCreated'];
$storeId = $decodedBody['storeId'];
$entityId = $decodedBody['entityId'];
$eventType = $decodedBody['eventType'];
$data = $decodedBody['data'];

All of the resulting variables except for the $data are of a string type. The $data variable is an object of strings.

Step 3. Verify webhook signature

After parsing the webhook body, get its X-Ecwid-Webhook-Signature header and validate webhook data with it using sha256 encryption.

Code example for webhook verification:

$client_secret = 'abcde123456789';

if (!$signatureHeaderPresent) {
	echo 'Signature verification failed';
	exit;
}

if (!function_exists('getallheaders')) {
    function getallheaders()
    {
        foreach ($_SERVER as $name => $value) {
            if (substr($name, 0, 5) == 'HTTP_') {
                $headers[str_replace(' ', '-', ucwords(strtolower(str_replace('_', ' ', substr($name, 5)))))] = $value;
            }
        }
        return $headers;
    }
}

foreach (getallheaders() as $name => $value) {
    if ($name == "X-Ecwid-Webhook-Signature") {
        $headerSignature = "$value";
      	$signatureHeaderPresent = true;
        
        $hmac_result = hash_hmac("sha256", "$eventCreated.$eventId", $client_secret, true);
        $generatedSignature = base64_encode($hmac_result);
        
        if ($generatedSignature !== $headerSignature) {
            echo 'Signature verification failed';
            exit;
        }
    }
}

After completing these steps, you can safely process the data received in the webhook.

Last updated 2 months ago

Was this helpful?