SEOshop Documentation


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.

curl \
  -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


PHP client example:

    'isActive'   => true,
    'itemGroup'  => 'orders',
    'itemAction' => 'created',
    'language'   => 'en',
    'format'     => 'json',
    'address'    => ''

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)


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:

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


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.