Work with events from Bluestone PIM

Learn how to subscribe to PIM updates

Bluestone PIM can post messages/notifications about updates to a given external URL. This is called a webhook. 

Please refer to Webhooks management on how to manage webhooks from the UI.
Please refer to External Notifications API on how to manage webhooks via the API.

Order of messages    Message delivery     

Create a webhook    Find webhook IDs     Subscribe to events

Order of messages

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.

Message delivery

If the subscriber is unavailable at the moment of delivery, the message might be retried later. This depends on the response status.

• Status code 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.
• Status code 401 or 403
  The delivery will not be retried.
• Other status codes
  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 given 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 via the Get messages endpoint. It is also possible to filter on the message status, e.g. 'SENT' or 'ERROR'.

Back to the top

Context in events

Events include three attributeChange properties that describe where a change was made and which contexts are impacted, accommodating both global and context-aware attributes with fallback behavior. See more information about languages and contexts and attributes in Bluestone PIM.

• context (legacy)
  The context label associated with the operation (e.g., "en", "no", "pl"). Kept for backward compatibility; prefer the fields below for logic and integrations going forward.

• contextId
  The context that the change applies to.

  • Global attributes: null (the value is shared across all contexts).

  • Context-aware attributes: equals the context value (e.g., "no").

• affectedContextIds
  Every context whose effective value may change due to this update.

  • Global attributes: all contexts defined for the organization

  • Context-aware attributes: depends on fallback relations

    • Editing a parent context (e.g., "en" when "no" falls back to "en"), the value will be: ["en","no"]

    • Editing a dependent context directly: just that context (e.g., ["no"])

    • Contexts without fallback: just that context

Back to the top

Create a webhook

https://docs.api.bluestonepim.com/reference/create-3

Parameter: active
Description: Messages will not be posted to webhook if inactive
Example value: true

Parameter: secret
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. 

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

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 IDs

https://docs.api.bluestonepim.com/reference/search-3

Get a list of webhooks including their IDs for your organization.

Subscribe to events

https://docs.api.bluestonepim.com/reference/subscribe

Subscribe to given events for given webhook. 

Name: webhookId
Description: ID of webhook
Example: 5df0ca49cff47e000df7809c

Name: eventTypes
Description: List of events to listen for. Comma-separated list of strings. 
Example:

{

  "eventTypes": [

    "PRODUCT_CREATED",

    "PRODUCT_SYNC_DONE"

  ]

}

Please refer to Event types for information about the different types and examples.

Back to the top