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. The subscription's secret is required; it is used to derive the x-shirtplatform-hmac-sha256 signature sent with every delivered event.

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. Required fields: address (callback URL), topic (subscribed event), and secret.
application/xml Webhook
Response Codes
Code Condition
200 the webhook subscription was created
400 validation failed (for example, the required secret is missing)
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.

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 id of a saved Filter.Webhook; an empty string returns all subscriptions
page query 0 int zero-based page index
size query 10 int number of items per page
Response Codes
Code Condition
200 the webhook subscriptions were successfully retrieved
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.

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 Codes
Code Condition
200 the webhook subscription was successfully retrieved
404 no webhook subscription exists for the given id in 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. The id and shop in the body are ignored; the path id identifies the subscription. Send a secret only to rotate it — an omitted secret leaves the existing one unchanged.

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 Codes
Code Condition
200 the webhook subscription was updated
404 no webhook subscription exists for the given id in the shop
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. Deleting an unknown subscription still succeeds; the operation is idempotent.

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 Codes
Code Condition
204 the webhook subscription was deleted, or did not exist
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 by triggering its subscribed order event. The subscription's own topic is dispatched for the given order exactly as a real event would be, letting you verify that your endpoint receives and validates the signed payload. No response body is returned.

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 Codes
Code Condition
204 the test event was dispatched
404 no webhook subscription exists for the given id, or no order exists for the given orderId
Response Body
Media Type Data Type Description
application/json object
application/xml anyType