Webhooks are a useful tool for apps that want to execute code after a specific event happens on a shop, for example, after a customer creates a cart on the storefront, or a merchant creates a new product in their admin.

Instead of telling your app to make an API call every X number of minutes to check if a specific event has occured on a shop, you can register webhooks, which send an HTTP POST request from the shop telling your app that the event has occurred. This uses many less API requests overall, allowing you to build more robust apps, and update your app instantly after a webhook is received.

Webhook event data can be stored as JSON, and is commonly used when:

• Placing an order
• Changing a product's price
• Create a customer
• Integrating your accounting software
• Removing customer data from your database when they uninstall your app

Webhook events

Webhooks can be registered for many events. Please check the public API for a full list.

Configure a webhook

The trouble with testing your webhooks through the API is that you need a publicly visible URL to handle them. Unlike client-side redirects, webhooks originate directly from the server. This means that you cannot use the following as an endpoint in your testing environment:

• Localhost
• "Fake" domains like www.example.com
• EasyStore domains (i.e. easy.co, easystore.co and www.easystore.co)

Receive a webhook

Once you register a webhook URL with EasyStore, we will issue a HTTP POST request to the URL specified every time that event occurs. The request's POST parameters will contain JSON data relevant to the event that triggered the request.

EasyStore verifies SSL certificates when delivering payloads to HTTPS webhook addresses. Please ensure your server is correctly configured to support HTTPS with a valid SSL certificate.

Respond to a webhook

Your webhook must acknowledge the data received by responding a "200 OK" status within 10 seconds.
If your response exceeds 10 seconds or has a non-200 status code, EasyStore will assume your webhook did not receive the data. EasyStore does not follow redirects (eg: "301 Redirect") for webhook notifications, and such redirections will be considered error responses.

Verify a webhook

Each webhook request includes EasyStore-Hmac-SHA256 header, which is generated using the app's shared secret along with the data sent in the request.

To verify that the request came from EasyStore, compute the HMAC digest according to the following algorithm and compare it to the value in the EasyStore-Hmac-SHA256 header. If they match, you can be sure that the Webhook was sent from EasyStore and the data has not been compromised.

Below is a simple example in PHP version of how to verify a webhook request.

	<?php

	define('EasyStore_APP_SECRET', 'my_shared_secret');

	function verify_webhook($data, $hmac_header)
	{
	  $calculated_hmac = hash_hmac('sha256', $data, EasyStore_APP_SECRET);
	  return hash_equals($hmac_header, $calculated_hmac);
	}

	$hmac_header = $_SERVER['EasyStore-Hmac-SHA256'];
	$data = file_get_contents('php://input');
	$verified = verify_webhook($data, $hmac_header);
	error_log('Webhook verified: '.var_export($verified, true));

	//check error.log to see the result

	?>