Working with Callbacks
OS1 allows you to capture events asynchronously and be automatically notified of CRUD events that pertain to OS1 services. This allows for a more efficient, responsive system, enabling apps to continue processing other tasks while waiting for service updates.
When your app sends us instructions to execute different operations, we respond via callbacks. With callbacks, consuming apps can specify where to send updates about requested CRUD operations, allowing real-time data processing and a more responsive application.
Follow the steps below to receive asynchronous updates:
Define a unique callback URL in your application that will receive the updates. Then, ensure the URL is publicly available and can handle incoming HTTP requests.
To listen to updates, send an API request to OS1 specifying your callback URL where we'll send the requested information.
See the sample request below for creating a Container:
Once we receive and process the API request, our system sends an update about the requested information to the defined callback URL with the following information:
- Event type: The type of event that triggered the update.
- Service: The event’s service type (Participant, Container, or Entity).
- Data: The data associated with the event.
Lastly, configure your app to handle callbacks using the following:
Your app should parse the incoming POST request to extract the event information when receiving a callback.
See the example below of the response payload sent to the callback URL for the Container creation mentioned above:
Based on the type of event and service, your app should perform the appropriate action, such as displaying a notification or triggering a specific workflow.
Once your app processes the update, your app should send one of the following HTTP responses acknowledging that the callback was accepted:
The Callback feature is used in different services of OS1. Signature verification is implied in the Callback system to prevent unexpected and unauthenticated loads on that service. Whenever a callback is received it can be verified at OS1.
- It provides the ability to register a token/secret.
- Return an HMAC signature with every callback.