This page will help you setup idempotent api calls
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), so 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 atthe 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 as the timestamp at which the usage occurred.
One approach you could take is to create a table in your db called something like SalesbricksUsageReportingRequests which could look something like
| db column name | description |
|---|---|
| salesbricks_idempotent_key (pk, uuid) | unique uuid you generate when you make the usage request to Salesbricks and which is your idempotency key value |
| internal_usage_id (str) | the id you use to identify usage internally in your system |
| (optional) created_at (timestamp) | timestamp at which you make the request to Salesbricks, for debugging |
| (optional) response_code(int) | response code you received from Salesbricks, for debugging |
| (optional) response (jsonb str) | response payload you received from Salesbricks, for debugging |
Then when you report your usage you:
- create a row in
SalesbricksUsageReportingRequestsstoring the timestamp, internal_usage_id and salesbricks_idempotent_key - make the request to salesbricks, specifying the salesbricks_idempotent_key in the
X-SALESBRICKS-IDEMPOTENT-OPERATION-KEYheader - save the response you get back in the
SalesbricksUsageReportingRequeststable.
If you got an error response such as a 400 where you sent an invalid request where the usage was not successfully reported, you can adjust the sending code to send the correct payload, and retry the steps above, generating a new salesbricks_idempotent_key for the new request.