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
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
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.
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
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:
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:
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:
To delete the webhook use webhook.delete method and fill in the webhook id.
For more API methods jump into our documentation.