Working with Webhooks

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

  1. 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.

  2. 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;

}


Lost connection with the store

In case API2Cart loses connection with a store due to any changes on the customer side (e.g. bridge deleted, store key changed, etc.), you will get the callback notification with empty body and additional headers:

X-Webhook-Error-Code - error code, other than 0.

X-Webhook-Error-Reason - issue report (e.g. ‘incorrect store key’).

X-Webhook-Error-Message - instruction on how to solve the issue and what will happen if the issue will not be solved.

X-Webhook-Error-Try-Count - the number shows how many tries left before we disable the webhook.

 

If the connection between API2Cart and the store is lost, the request interval will increase accordingly to the number of failed attempts to connect.

After five failed requests, the webhook will be disabled.

To activate this webhook, change the parameter to active using webhook.update 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:

  • callback

  • label

  • fields

  • active

To delete the webhook use webhook.delete method and fill in the webhook id.


For more API methods jump into our documentation.