You can use webhook subscriptions to receive notifications about particular events in your shops. After you've subscribed to a webhook, you can let your app execute code immediately after specific events occur in your shops.

For example, you can rely on webhooks to trigger an action in your app when a customer creates a new order or shirtplatform fulfills an order.

By using webhooks subscriptions you can make fewer API calls overall, which makes sure that your apps are more efficient and update quickly.

Webhook chart
POST /accounts/{accountId}/shops/{shopId}/webhooks

Create a new webhook subscription.

Available Since
1.3.0
Parameters
Name In Default Constraints Description
x-auth-token header     The authentication token
accountId required path   int the unique identifier of the account
shopId required path   int the unique identifier of the shop
Request Body
Media Type Data Type Description
application/json Webhook the webhook subscription data including callback URL and subscribed events
application/xml Webhook
Response Body
Media Type Data Type Description
application/json Webhook
application/xml Webhook
Request (XML) 
<webhook>
  <id>...</id>
  <address>https://whatever.hostname.com/</address>
  <topic>orders/updated</topic>
  <secret>mysecretword</secret>
  <mediaType>JSON</mediaType>
</webhook>
Request (JSON) 
{
  "webhook" : {
    "id" : 12345,
    "address" : "https://whatever.hostname.com/",
    "topic" : "orders/updated",
    "secret" : "mysecretword",
    "mediaType" : "JSON"
  }
}
Response (XML) 
<webhook>
  <id>...</id>
  <address>https://whatever.hostname.com/</address>
  <topic>orders/updated</topic>
  <secret>mysecretword</secret>
  <mediaType>JSON</mediaType>
</webhook>
Response (JSON) 
{
  "webhook" : {
    "id" : 12345,
    "address" : "https://whatever.hostname.com/",
    "topic" : "orders/updated",
    "secret" : "mysecretword",
    "mediaType" : "JSON"
  }
}
GET /accounts/{accountId}/shops/{shopId}/webhooks

Get a list of webhook subscriptions for your shop.

Available Since
1.3.0
Parameters
Name In Default Constraints Description
x-auth-token header     The authentication token
accountId required path   int the unique identifier of the account
shopId required path   int the unique identifier of the shop
filterId query   optional saved Filter.Webhook ID; empty string for all
page query 0 int zero-based page index
size query 10 int number of items per page
Response Body
Media Type Data Type Description
application/json PagedData
application/xml PagedData
Response (XML) 
<pagedData>
  <records>...</records>
  <totalElements>...</totalElements>
</pagedData>
Response (JSON) 
{
  "pagedData" : {
    "records" : [ { }, { } ],
    "totalElements" : 12345
  }
}
GET /accounts/{accountId}/shops/{shopId}/webhooks/{id}

Get a single webhook by its id.

Available Since
1.3.0
Parameters
Name In Default Constraints Description
x-auth-token header     The authentication token
accountId required path   int the unique identifier of the account
id required path   int the unique identifier of the webhook subscription
shopId required path   int the unique identifier of the shop
Response Body
Media Type Data Type Description
application/json Webhook
application/xml Webhook
Response (XML) 
<webhook>
  <id>...</id>
  <address>https://whatever.hostname.com/</address>
  <topic>orders/updated</topic>
  <secret>mysecretword</secret>
  <mediaType>JSON</mediaType>
</webhook>
Response (JSON) 
{
  "webhook" : {
    "id" : 12345,
    "address" : "https://whatever.hostname.com/",
    "topic" : "orders/updated",
    "secret" : "mysecretword",
    "mediaType" : "JSON"
  }
}
PUT /accounts/{accountId}/shops/{shopId}/webhooks/{id}

Update a webhook subscription.

Available Since
1.3.0
Parameters
Name In Default Constraints Description
x-auth-token header     The authentication token
accountId required path   int the unique identifier of the account
id required path   int the unique identifier of the webhook subscription
shopId required path   int the unique identifier of the shop
Request Body
Media Type Data Type Description
application/json Webhook the updated webhook subscription data
application/xml Webhook
Response Body
Media Type Data Type Description
application/json Webhook
application/xml Webhook
Request (XML) 
<webhook>
  <id>...</id>
  <address>https://whatever.hostname.com/</address>
  <topic>orders/updated</topic>
  <secret>mysecretword</secret>
  <mediaType>JSON</mediaType>
</webhook>
Request (JSON) 
{
  "webhook" : {
    "id" : 12345,
    "address" : "https://whatever.hostname.com/",
    "topic" : "orders/updated",
    "secret" : "mysecretword",
    "mediaType" : "JSON"
  }
}
Response (XML) 
<webhook>
  <id>...</id>
  <address>https://whatever.hostname.com/</address>
  <topic>orders/updated</topic>
  <secret>mysecretword</secret>
  <mediaType>JSON</mediaType>
</webhook>
Response (JSON) 
{
  "webhook" : {
    "id" : 12345,
    "address" : "https://whatever.hostname.com/",
    "topic" : "orders/updated",
    "secret" : "mysecretword",
    "mediaType" : "JSON"
  }
}
DELETE /accounts/{accountId}/shops/{shopId}/webhooks/{id}

Delete a webhook subscription.

Available Since
1.3.0
Parameters
Name In Default Constraints Description
x-auth-token header     The authentication token
accountId required path   int the unique identifier of the account
id required path   int the unique identifier of the webhook subscription
shopId required path   int the unique identifier of the shop
Response Body
Media Type Data Type Description
application/json object
application/xml anyType
POST /accounts/{accountId}/shops/{shopId}/webhooks/{id}/testOrderEvent/{orderId}

Test a webhook subscription. It will trigger a predefined shop event on the specified order.

Available Since
1.3.0
Parameters
Name In Default Constraints Description
x-auth-token header     The authentication token
accountId required path   int the unique identifier of the account
id required path   int the unique identifier of the webhook subscription to test
orderId required path   int the unique identifier of the order to use for the test event
shopId required path   int the unique identifier of the shop
Response Body
Media Type Data Type Description
application/json Webhook
application/xml Webhook
Response (XML) 
<webhook>
  <id>...</id>
  <address>https://whatever.hostname.com/</address>
  <topic>orders/updated</topic>
  <secret>mysecretword</secret>
  <mediaType>JSON</mediaType>
</webhook>
Response (JSON) 
{
  "webhook" : {
    "id" : 12345,
    "address" : "https://whatever.hostname.com/",
    "topic" : "orders/updated",
    "secret" : "mysecretword",
    "mediaType" : "JSON"
  }
}