Overview
Callbacks, also known as webhooks, notify your platform and users of any state changes, helping complete the information loop when using the Assembly service. Callbacks are a useful way of notifying you when statuses or transactions change. For example; if an Item changes state because we have processed an Direct Debit/ACH payment, we will POST a JSON payload with the Item object attributes to the URL provided. Callbacks allow you to initiate dependent processes or notifications based on updates from Assembly. For example; sending goods to a purchaser when their Direct Debit/ACH payment is successfully received.
Security
There are a few measures that can be taken to ensure callbacks are secure. Only HTTPS URLs are supported and require a valid SSL certificate. Self-signed certificates are not supported.
Method | Description |
---|---|
IP Whitelisting | Whitelist the IPs 54.183.18.207 & 54.183.142.227. These are the IPs that callbacks will be sent from. |
URL Obfuscation | When creating a callback POST endpoint, use an obfuscated URL to ensure it cannot be easily accessed by an insecure source. Example: https://example.com/callbacks/items/1bb77e2f892ebab9b2 |
Secondary API Call | Using the ID provided within the callback, you can initiate another API call to fetch the resource from Assembly once again. This ensures the request and response occur between both backends. Example: A callback of GET /items/:id reaches the endpoint. In the payload there is an ID. Using the ID, make a call to GET /items/:id to ensure the data is coming from the Assembly API. |
Types of Callbacks
Only one Callback can be enabled for an object type. Each of these callbacks will return the response of the ‘Show’ of that object. For example, a callback for Items will return the GET /items/:id response.
Callback (object) | Triggers | Examples |
---|---|---|
Items | Any data changes for that Item. Typically used whenever the state of the object changes. |
|
Users | Any data changes for that User. Typically used whenever the state of the object changes. |
|
BatchTransactions | On creation of any BatchTransactions and whenever the state changes. |
|
BankAccounts | When the state or enabled status of the bank account changes. No data can be changed on an existing account. |
|
Transactions | On creation of any Transactions and whenever the state changes. |
|
Walkthrough
1) Create a callback
Use Create Callback to create your callback within Assembly. Pass a valid HTTPS URL that will accept a POST request. This URL will receive a POST call when the callback object is triggered. When creating a Callback, the URL provided will be sent a test JSON payload and will only be successfully created if the response created is successful.
The output of the test you will receive from us is:
{ message: 'Assembly Payments callback test'}
2) Trigger callback
To trigger a callback, update the object you have created a callback for. An example of this would be to Make Payment for an Item, if the callback you created was for an Item.
3) List callback responses
Use List Callback Responses to view a list of the triggers for the callback you created. Each time the callback is triggered, a response will be added.
Testing
There are a number of ways to start testing callbacks with Assembly. We recommend services such as Request Bin and Runscope, both of which can be used to provide a container for all callbacks to be sent to.
Comments
0 comments
Please sign in to leave a comment.