Working with Webhooks

API2Cart webhook is a mechanism for getting notifications when some changes or events on shopping carts occur. For example, the order.update webhook triggers every time when the order status changes. In this case, the JSON formatted data is being sent to the specified URL.

The webhook creation

First check which webhooks are supported for the given store. To do this, call webhook.events method. You will get the list of webhooks that are supported for the given shopping cart.
Then create the webhook by calling webhook.create method. This is the example of creating the webhook that sends events about new products on the store.

Use the webhook.create and specify the following parameters api_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx store_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx entity = product action = add callback = http://exmple.com label = super_webhook fields = id,name Here is the example of the request for creating a webhook https://api.api2cart.com/v1.0/webhook.create.json? api_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&store_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx &entity=product&action=add&callback=http%3A%2F%2Fexmple.com&label=super_webhook&fields=id,name See more details about the parameters on our documentation. Note: In case you are using multi store instance you can set store_id parameter to specify on which store you want create the webhook. If the request is performed successfully and you will received the id of the webhook that you’ve just created. From now on, when new product appears on the store, you will receive webhook events on the URL, which you’ve specified in callback parameter.

The information about the events that are sent to the callback The events that will be sent to the callback URL contain additional header with the event info. X-Webhook-Store-Id – store id, that the event has occurred on. For non-multistore instances the returned value will always be “1”. X-Webhook-Action – the event that occured (add, update, delete) X-Webhook-Entity – the entity that the event occurred with (product, order, etc.) X-Webhook-Error-Code - error code. If successful, the code equals 0. The body contains json string with new data about the entity. Example Headers X-Webhook-Store-Id: 1 X-Webhook-Action: add X-Webhook-Entity: product X-Webhook-Error-Code: 0 Body {"id":"86","name":"test product"} The event is considered to be successfully delivered when the callback returns status code 200. In case the status code is anything but 200, the system sends the event one more time. If this time the status code is also not 200, then it is considered to be undelivered and it will appear in the failed events log. You can check the list of failed events using account.failed_webhooks method. NB! We store failed webhooks data for 24 hours.

Authenticating Webhook Requests

API2Cart signs webhook events so you can validate that requests are sent by API2Cart and not a third-party pretending to be API2Cart. API2Cart includes an X-Webhook-Signature header generated using the app's shared secret, along with the data sent in the request in each Webhook event. To verify that the request came from API2Cart, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Webhook-Signature header. What you need to generate a signature: 1. Headers of the request 2. Request body 3. Store_key Generating Signature: 1. Gather all headers starting with “X-Webhook-”. 2. Remove “X-Webhook-Signature” from the array. 3. Sort the headers alphabetically by the key. 4. Encode the headers into JSON. 5. Concatenate the strings, JSON headers string should come first. 6. Hash the resulting string with HMAC SHA256 function with outputs raw binary data set true (raw_output = true). Use your store_key as a secret key to generate a binary signature. 7. Encode the string in Base64.

Example of PHP implementation:

$headersForJson = [
    'X-Webhook-Error-Code' => '0',
    'X-Webhook-Action' => 'update',

    'X-Webhook-Timestamp' => '1516291592',

    'X-Webhook-Entity' => 'product',

    'X-Webhook-Store-Id' => '1',

    'X-Webhook-Signature' => 'SGVsbG8gd2l0aCBBUEkyQ2FydA==',

  ];

$signatureFromRequest = $headersForJson['X-Webhook-Signature'];

unset($headersForJson['X-Webhook-Signature']);

ksort($headersForJson);

$headers = json_encode($headersForJson);

$data = $headers . $params['raw_body'];

$generatedSignature = base64_encode(hash_hmac('sha256', $data, $storeKey, true));

if (hash_equals($signatureFromRequest, $generatedSignature)) {

 return true;

}

Please pay extra attention to the case of the headers so that your signature matches. Headers should be in the same case as in our example.

Lost connection with the store

method (see details of webhook parameters below).

What else you can do with the webhooks Using webhook.list method you can get the list of webhooks that were created in the store via API2Cart API. The created webhook contain the following fields: "id" – The webhook id "label" – The webhook name "store_id" – The store id the webhook is created on. For non-multistore instances the returned value will always be “1”. "active" – Webhook status "callback" - Callback URL that the webhook will send the POST request to when the event occurs "fields" - Fields that the webhook will send "created_at" – Webhook creation date "updated_at" – Last webhook update date "entity" – The entity that the webhook is created for "action" - The action that triggers the webhook You can filter the webhooks according to different fields. There are the the following parameters for this:

entity
action
active
ids

For details see the documentation. You can also check the number of created webhooks on the store using webhook.count method. You can change some webhook parameters using webhook.update method. To do this, you need to fill its id. You can change only the following parameters: