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.