Idempotent Requests
To ensure idempotent requests, include the X-SALESBRICKS-IDEMPOTENT-OPERATION-KEY header in your requests to Salesbricks.
This key is crucial for identifying and de-duplicating specific requests, safeguarding against unintended duplication.
Header Key
The header key should be X-SALESBRICKS-IDEMPOTENT-OPERATION-KEY.
Header Value
An idempotency key is a unique-to-you value generated by you, the client, which the server uses to identify a specific request and de-duplicate it from subsequent retries of the same request.
How you create unique keys is up to you, but we suggest including UUIDs or other unique IDs as part of the value to avoid collisions.
Idempotency keys can be up to 255 characters long.
The key should be used to identify the request, not just the data being sent (as even failure requests are saved).
We recommend generating and storing a key per-request-to-Salesbricks (see example below).
Handling of Duplicate Idempotency Keys
Subsequent Requests with the same idempotency and same payload
Salesbricks saves the response of the first request made for any given idempotency key, regardless of whether it succeeded or failed.
Subsequent requests with the same key return the same result.
This means if you received an error response on a request made with an idempotency key, a following request using that same key will return that same error response.
This is true for any error response, including 500 errors, as long as the request actually made it to Salesbricks’ servers.
Subsequent Requests with the same idempotency key but a different payload
The idempotency system also compares incoming requests to the original request and errors, unless they’re the same, to prevent accidental misuse.
If you send a request with the same key but a different payload, you will receive a status code 400 error in response.
Duplicate Concurrent Requests with the same idempotency keys
If you send 2 requests with the same idempotency key to Salesbricks, the requests will be processed serially, and the one which is processed later will return a status code 409 to indicate a conflict.
Example Implementation
Let’s say you would like to report usage on an order tracked in Salesbricks. Let’s also say you track the usage for the order internally using the timestamp at which the usage occurred.
One approach you could take is to create a table called SalesbricksUsageReportingRequests in your database, which could look something like:
| DB column name | Description |
|---|---|
salesbricks_idempotent_key (pk, uuid) | A UUID which is your idempotency key value, that you generate when you make the usage request to Salesbricks |
internal_usage_id (str) | The ID you use to identify usage internally in your system |
created_at (optional, timestamp) | Timestamp at which you make the request to Salesbricks, for debugging |
response_code (optional, int) | Response code you received from Salesbricks, for debugging |
response (optional, jsonb str) | Response payload you received from Salesbricks, for debugging |
Then, when you report your usage, you:
Create a row in SalesbricksUsageReportingRequests storing the created_at timestamp, internal_usage_id and salesbricks_idempotent_key.
Make the request to Salesbricks, specifying the salesbricks_idempotent_key in the X-SALESBRICKS-IDEMPOTENT-OPERATION-KEY header.
Save the response you get back in the SalesbricksUsageReportingRequests table.
If you got an error response such as a 400, in which you sent an invalid request where the usage was not successfully reported, you can adjust the sending code to send the correct payload.
Then, retry the steps above, generating a new salesbricks_idempotent_key for the new request.