Handling callbacks from Brightpearl

When a Brightpearl customer installs your app, an unsigned account token is generated, unique to the relationship between your app and the customer’s account. To enable you to get these tokens, and track which Brightpearl customers have your integration installed and enabled, we provide a callback mechanism.

Configuring callbacks

When you configure your app, you can supply URLs on your server for install and uninstall callbacks. We’ll make a call to the supplied install URL when a customer first installs your app, and a call to the uninstall URL if they choose to disable or remove it. If the customer re-enables your app after disabling it, we’ll call your install URL again.

You don’t have to provide install and uninstall callback URLs if your app doesn’t need to track active accounts, but if you make API calls to accounts based on a schedule or in response to events in a third party system, we recommend you implement tracking.

For security we recommend you use HTTPS for callback URLs. You can include query parameters in your URL, but to avoid conflicts, be careful not to use the same parameter names we send.

Bear in mind that you may miss callbacks if there is a network outage or other technical problem, so your list of active accounts is not guaranteed to be accurate if you only use callbacks to update it. To keep up to date, you can use the installed account API to get a list of accounts and their tokens.

Link signing

So that you can verify callbacks as originating from Brightpearl, we sign the parameters included in the callback using your developer secret. To avoid the possibility of an attacker sending fake callbacks to your system, you should verify the signature.

Here’s a worked example showing how to verify a signature:

Your callback URL: https://example.com/install?app=parcelforce

Callback received:

https://example.com/install?app=parcelforce×tamp=112287235486&accountCode=topfurniture&signature=20e538aec7d2568b898a13bea7814b962d270cb364a5517fc29f8ab4ca6cd9db

1. Create a map of the query parameters. The set of parameters we send may occasionally change, so include all the parameters you receive. Don't hard code parameter names from this example list!

[ app = parcelforce, timestamp = 112287235486, accountCode = topfurniture, signature = 20e538aec7d2568b898a13bea7814b962d270cb364a5517fc29f8ab4ca6cd9db ]

2. Remove the signature parameter, and any parameters you included in the callback URL you gave us.

[ timestamp = 112287235486, accountCode = topfurniture ]

3. Sort the map alphabetically by key.

[ accountCode = topfurniture, timestamp = 112287235486 ]

4. Join the map entries into a string with = between each key and its value, and no separator between each key value pair.

accountCode=topfurnituretimestamp=112287235486

5. Prepend your developer secret.

fcVGPrRapgRyT83CJb9kg8wBpgIV7tdKikdKA/7SmvYaccountCode=topfurnituretimestamp=112287235486

6. Create a hex encoded SHA-256 hash of this string.

20e538aec7d2568b898a13bea7814b962d270cb364a5517fc29f8ab4ca6cd9db

7. If this hashed string matches the signature parameter on the callback, it is genuine.

Install callbacks

When a customer installs or re-enables your app in their account, we will send an install callback to the URI you supplied.

These are the parameters we supply on an install callback:

accountCode The Brightpearl customer’s account code.
token An unsigned account token. See the API authentication page for details on.
timestamp The current epoch time in milliseconds. If you wish, you can verify this is close to the actual time.
signature Query string parameters signed with your developer secret for verification as described above.

Uninstall callbacks

When a customer disables or removes your app in their account, we will send an uninstall callback to the URI you supplied.

These are the parameters we supply on an uninstall callback:

accountCode The Brightpearl customer’s account code.
timestamp The current epoch time in milliseconds. If you wish, you can verify this is close to the actual time.
signature Query string parameters signed with your developer secret for verification as described above.
 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.