Webhook

Webhooks are user-defined callbacks which are triggered by some events. It allows You easily develop push notifications. This notification is simply a HTTP POST request to a given web server url address.
But remember they are not real time. They can be delayed and out of date. Below You will find complete list of events on which You can register webhooks.


Supported Events

  • category/create
  • category/update
  • category/delete
  • checkout/create
  • checkout/update
  • checkout/delete
  • collection/create
  • collection/update
  • collection/delete
  • customer/create
  • customer/update
  • customer/delete
  • order/create
  • order/update
  • order/delete
  • order/paid
  • order/cancelled
  • orderStatus/create
  • orderStatus/update
  • orderStatus/delete
  • orderStatus/paid
  • product/create
  • product/update
  • product/delete
  • shop/update
  • vendor/create
  • vendor/update
  • vendor/delete
  • app/uninstalled

If You want to set up a webhook just choose a specific section, set an address to your server and Shoplo will inform You whenever a given event occurs.

When the request fails, don't worry. Shoplo will attempt to re-send the request again with the following schema until receive a positive response: 1 minute, 5 minutes, 10 minutes, 20 minutes, 30 minutes, 1 hour, 2 hours, 4 hours and every 4 hours up to 48 hours. If in this time Shoplo could not connect to a given address, Shoplo will automatically remove the webhook.


Webhooks Authentication

Each POST request header send by Shoplo contains a HTTP_SHOPLO_HMAC_SHA256 header to authenticate the payload. You can verify a webhook using your secret app key and received data from the request. To verify the request You need to compute a HMAC digest with the algorithm describe below and next compare it with the value receive from HTTP_SHOPLO_HMAC_SHA256 header.

Below You can find examle how to werify a webhhok request in PHP.


<?php

define('SHOPLO_APP_SECRET', 'my_secret_key');

$hmac_key = $_SERVER['HTTP_SHOPLO_HMAC_SHA256'];
$calculated_key = base64_encode(hash_hmac('sha256', http_build_query($_POST), SHOPLO_APP_SECRET));
if ( $hmac_key != $calculated_key )
{
	echo "Request compromised!!!";
}

?>

Common Headers

While Shoplo send a request after specific event occurs, it add additional headers to request:

  • shoplo-section - event sectio (order/create, product/delete, etc.)
  • shoplo-shop-id - identifier of a shop in which event occur
  • shoplo-hmac-sha256 - computed HMAC digest
  • shoplo-{object_type}-id - identifier of an object which cause an event
  • shoplo-{object_type}-uuid - unique identifier of an object which cause an event

To get more informations about webhooks, read PBWiki Webhooks page.


Receive a list of all Webhooks

Query parameters
  • limit - Amount of results (default - 50) (max limit - 200)
  • page - Page to shop (default is 1)
  • section - Show webhooks with a given section. One of the: category/create, category/update, category/delete collection/create, collection/update, collection/delete, customer/create, customer/update, customer/delete order/create, order/update, order/delete, order/paid, product/create, product/update, product/delete vendor/create, vendor/update, vendor/delete, app/uninstalled
  • site_url - Show webhooks with a given site url
  • fields - List of fields returning in response
GET /services/webhooks

Receive a list of all Webhooks

Response
HTTP/1.1 200 OK
{
  	"webhooks": [
		{
			"created_at" : "2011-05-08 21:26:27",
			"format" : "json",
			"id" : 1
			"section" : "order/create",
			"site_url" : "https://example.com/event/order/create",
			"updated_at" : "2011-05-08 21:26:27",
		},
		{
			"created_at" : "2011-06-12 12:43:45",
			"format" : "json",
			"id" : 2
			"section" : "product/update",
			"site_url" : "https://example.com",
			"updated_at" : "2011-06-12 12:43:45",
		},
	]
}

Receive a count of all Webhooks

Query parameters
  • section - Count webhooks with a given section
  • site_url - Count webhooks with a given site url
GET /services/webhooks/count

Receive a count of all Webhooks

HTTP/1.1 200 OK
{
	"count": 5
}

Receive a single Webhook

Query parameters
  • fields - List of fields returning in response
GET /services/webhooks/{id}

Receive a single Webhook

Response
HTTP/1.1 200 OK
{
	"webhook": {
		"created_at" : "2011-05-08 21:26:27",
		"format" : "json",
		"id" : 1
		"section" : "order/create",
		"site_url" : "https://example.com/event/order/create",
		"updated_at" : "2011-05-08 21:26:27",
	},
}

Create a Webhook

POST /services/webhooks

Creating a new webhook help Your app to have almost in real-time push notifications

Request
{
	"webhook": {
		"section" : "order/create",
		"site_url" : "https://example.com/event/order/create",
	}
}
Response
HTTP/1.1 200 OK
{
	"webhook": {
		"created_at" : "2011-05-08 21:26:27",
		"format" : "json",
		"id" : 1
		"section" : "order/create",
		"site_url" : "https://example.com/event/order/create",
		"updated_at" : "2011-05-08 21:26:27",
	},
}

Update an existing Webhook

PUT /services/webhooks/{id}

You can update a topic and/or site_url of a given webhook

Request
{
	"webhook": {
		"id" : 1,
		"section" : "order/create",
		"site_url" : "https://example.com/event/order/create",
	}
}
Response
HTTP/1.1 200 OK
{
	"webhook": {
		"created_at" : "2011-05-08 21:26:27",
		"format" : "json",
		"id" : 1
		"section" : "order/create",
		"site_url" : "https://example.com/event/order/create",
		"updated_at" : "2011-05-08 21:26:27",
	},
}

Delete an existing Webhook

DELETE /services/webhooks/{id}

Delete an existing webhook from a shop

Response
HTTP/1.1 200 OK
{}