Bluestone PIM can post messages/notifications to a given external URL. This is called a webhook. Webhooks are managed under settings in Bluestone PIM IU or External Notifications API.
Order Delivery Create a webhook Find webhook ID Subscribe to events Event types
Order
Messages are not guaranteed to be in the correct order. A product-created message is likely sent before the product updated message, but it is not guaranteed.
If the order of events are critical, it is recommended not to use data from the message directly. Instead, it should be treated as a signal that something has changed. Use API calls to origin to get the latest information.
Link: https://bluestonepim.readme.io
Password: Contact us on the chat, and we will send you the password.
Delivery
If the subscriber is unavailable at the moment of delivery, the message might be retried later. This depends on the response status.
- If the status code is 503 or 429, the time to wait will be decided by looking at the "Retry-After" header in the response. If this header is missing, the delivery will not be retried.
- If the status code is 401 or 403, the delivery will not be retried.
- For all other status codes, the delivery will be retried two times with a ten minute interval.
If the total number of failed delivery attempts for a webhook exceeds a certain threshold, the webhook will be blocked for a while. The threshold and the blocking time can vary between environments.
A log of messages, including the content of the message and the response from subscriber, is available in Get messages endpoint. It is also possible to filter on the message status, SENT or ERROR for example.
Create a webhook
https://bluestonepim.readme.io/reference#create-2
Parameter: url
Description: The URL that receives the message. This will always be an HTTP(s) POST. Use http://webhook.site/ to test
Example value: http://webhook.site/6e124229-d797-4551-8451-d2fb0f21b10a
Parameter: active
Description: Messages will not be posted to webhook if inactive
Example value: true
Parameter: active
Description: A password made by a subscriber. It can be used to validate that the message is legitimate. All messages will be signed with a SHA256 hash based on the request payload and this secret. This signature will be included in the request header x-bs-signature.
Use https://www.freeformatter.com/hmac-generator.html and select SHA256 to see how this works.
Example value: LongAndSecretPassword
Back to the top
Find webhook ID
https://bluestonepim.readme.io/reference#search-1
Get a list of webhooks for organizations and find the ID.
Subscribe to events
https://bluestonepim.readme.io/reference#subscribe
Subscribe to events of interest.
Name: webhookId
Description: Id of webhook
Example: 5df0ca49cff47e000df7809c
Name: eventTypes
Description: List of events to listen for. Comma-separated list of strings. See the overview of possibilities below.
Example:
{
"eventTypes": [
"PRODUCT_CREATED",
"PRODUCT_SYNC_DONE"
]
}
Event Types
Asset Attribute Label. Category Variant Bundle Created Metadata State Relation Sync done
Name: PRODUCT_WATCH_ASSET
Description: Change in product assets in PIM.
Example request body: Asset added to a product.
{
"timestamp": 1576066732167,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_ASSET",
"entityIds": [
"5d9af8844cedfd000c4fbfc3"
],
"assetChange": {
"changeType": "ASSOCIATE",
"assetId": "47e8e2c9-0d04-4e36-a809-558f914e6768"
}
}
}
]
}
Back to event types
Name: PRODUCT_WATCH_ATTRIBUTE
Description: Changes for attributes on a product in PIM.
Example request body: Asset added to a product.
{
"timestamp": 1576068300117,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_ATTRIBUTE",
"entityIds": [
"5df0cb01590801000d9f55eb"
],
"attributeChange": {
"changeType": "ASSOCIATE",
"attributeType": "text",
"attributeId": "5da7254de21b84000c6ed075",
"attributeOldValue": null,
"attributeNewValue": null
}
}
}
]
}
Back to event types
Name: PRODUCT_WATCH_LABEL
Description: Change a label on a product in PIM.
Example request body: Label added to a product.
{
"timestamp": 1576066907034,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_LABEL",
"entityIds": [
"5df0caaf713c09000cd64601"
],
"labelChange": {
"changeType": "ASSOCIATE",
"labelId": "5df0df59e82886000cf16373"
}
}
}
]
}
Back to event types
Name: PRODUCT_WATCH_CATEGORY
Description: Changes for a category on a product in PIM.
Example request body: Product added to a category.
{
"timestamp": 1576068145018,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_CATEGORY",
"entityIds": [
"5df0cb01590801000d9f55eb"
],
"categoryChange": {
"changeType": "ASSOCIATE",
"categoryId": "5d78f916ee3588000c7686e5"
}
}
}
]
}
Name: PRODUCT_WATCH_VARIANT
Description: Product added or removed from variant in PIM.
Example request body: Product added to a variant.
{
"timestamp": 1576067672492,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_VARIANT",
"entityIds": [
"5db18ff5dc0e82000ed896f4"
],
"variantChange": {
"changeType": "ASSOCIATE",
"variantId": "5da42f4052faff000c476117"
}
}
}
]
}
Back to event types
Name: PRODUCT_WATCH_BUNDLE
Description: Product added or removed from a bundle in PIM.
Example request body: Product being added to bundle.
{
"timestamp": 1576066651982,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_BUNDLE",
"entityIds": [
"5d9af8844cedfd000c4fbfc3"
],
"bundleChange": {
"changeType": "ASSOCIATE",
"bundleId": "5df0cb01590801000d9f55eb"
}
}
}
]
}
Back to event types
Name: PRODUCT_CREATED
Description: New product of any type created in PIM.
Example request body: Product created.
{
"timestamp": 1576061698388,
"events": [
{
"changes": {
"eventType": "PRODUCT_CREATED",
"entityIds": [
"5df0cb01590801000d9f55eb"
],
"metadataChanges": [
{
"field": "NAME",
"oldValue": null,
"newValue": "Product name"
},
{
"field": "NUMBER",
"oldValue": null,
"newValue": "123"
}
]
}
}
]
}
Back to event types
Name: PRODUCT_WATCH_METADATA
Description: Name, number, or description has changed on a product in PIM.
Example request body: A product name change.
{
"timestamp": 1576061982277,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_METADATA",
"entityIds": [
"5da42f4052faff000c476117"
],
"metadataChange": {
"field": "NAME",
"oldValue": "Phone2",
"newValue": "Phone3"
}
}
}
]
}
Back to event types
Name: PRODUCT_WATCH_STATE
Description: Change on product state in PIM.
Example request body: Product published.
{
"timestamp": 1576066839386,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_STATE",
"entityIds": [
"5df0caaf713c09000cd64601"
],
"stateChange": {
"changeType": "UPDATE",
"oldValue": "PLAYGROUND_ONLY",
"newValue": "TO_BE_PUBLISHED"
}
}
}
]
}
Back to event types
Name: PRODUCT_WATCH_RELATION
Description: Changes in relations on products in PIM
Example request body: Relation added to a product
{
"timestamp": 1576068014801,
"events": [
{
"changes": {
"eventType": "PRODUCT_WATCH_RELATION",
"entityIds": [
"5df0cb01590801000d9f55eb"
],
"relationChange": {
"changeType": "ASSOCIATE",
"relationId": "5d9d817fd60180000cc2bb54",
"connectedProductId": "5df0db256b2f07000c0f5dd1"
}
}
}
]
}
Back to event types
Name: PRODUCT_SYNC_DONE
Description: New sync done to Public API.
Example request body: Sync done.
{
"timestamp": 1576067842736,
"events": [
{
"changes": {
"eventType": "PRODUCT_SYNC_DONE",
"entityIds": [],
"syncDoneData": {
"field": "PAPI_SYNC_ID",
"value": "5df0e30002920b0010947c7d"
}
}
}
]
}