SEOshop Documentation

Webhooks

Using webhooks can greatly reduce the amount of API calls made. Webhooks will be fired when an event occurs. You can, for example, set up a webhook that will call a URL on your side of the application when a new order has been created or a payment has been made.

Creating a webhook

To create a webhook you need to do a POST request to the /webhooks.json resource. Make sure the webhook isn't already added because otherwise the webhook will be added twice. Webhooks are deleted automatically when a merchant uninstalls the app.

More documentation about the API resource is available at Resource > Webhooks.

Example
curl https://api.webshopapp.com/en/webhooks.json \
  -u key:secret \
  -d webhook[isActive]="true" \
  -d webhook[itemGroup]="orders" \
  -d webhook[itemAction]="created" \
  -d webhook[language]="en" \
  -d webhook[format]="json" \
  -d webhook[address]="itemGroup"
Create a new webhook

Request:
https://<api_key>:<api_token>@api.webshopapp.com/<shop_language>/webhooks.json

PHP client example:

<?php
$api->webhooks->create(array(
    'isActive'   => true,
    'itemGroup'  => 'orders',
    'itemAction' => 'created',
    'language'   => 'en',
    'format'     => 'json',
    'address'    => 'http://www.yourdomain.com/webhooks/order-created'
));

Available webhook groups:

  • customers
  • invoices
  • orders
  • products
  • quotes
  • reviews
  • shipments
  • subscriptions
  • tickets
  • variants

Available webhook actions:

  • created
  • updated
  • deleted
  • paid (only for orders)
  • shipped (only for orders)
  • answered (only for tickets)

Headers

Each webhook request holds a series of custom headers with useful information that are sent alongside the payload.
A list of possible headers:

  • X-Shop-Id - The shop ID
  • X-Format - Format of the payload (JSON|XML)
  • X-Language - ISO 639-1 code of a language (two letters)
  • X-Group-Id - The ID of the object involved where Group is one of the above groups
  • X-RateLimit-Limit - The current rate-limits for this API-key (5min/1hr/1day)
  • X-RateLimit-Remaining - The amount of calls left for the given time-interval (5min/1hr/1day)
  • X-RateLimit-Reset - The end of a given time-interval (5min/1hr/1day)
  • X-Cluster-Id - The cluster that has sent the webhook (us1 or eu1)

Validating a webhook

A webhook that is fired can be validated with the hash in the custom header X-Signature.

PHP example:

<?php
$input     = file_get_contents('php://input');
$payload   = !empty($input) ? $input : '';
$headers   = apache_request_headers();
$signature = isset($headers['X-Signature']) ? $headers['X-Signature'] : null;

if ($signature === null || $signature != md5($payload . $apiSecret))
{
    throw new Exception('Could not validate signature');
}

Note: the custom header X-Signature will only be available when the webhook is created from an app, not when direct connecting to the API.

Response

The server expects a webhook to respond with a 2xx HTTP-status (anything between 200 and 299) within 5 seconds. If the webhook responds with any other status, the call will be considered as failed. The server will retry a webhook multiple times with increasing delays within the next 24 hours. In total the webhook will be tried a maximum of 10 times.

Was this article helpful? Yes No
One moment please
Thanks for your feedback.