Callback API

What are Callback APIs?

APIs send data when requested, but callbacks can send data when an event is triggered to the callback url. So the client doesn't need to check repeatedly, if new data is available.

A Callback API is defined by the service calling the API. (Also referred to as a Webhook or Reverse API)

e.g. When a Callback API is called, the responder must handle the request and provide a response that conforms to what the caller expects.

Here is an example of a callback API with callback url.

POST /api.example.com/foo?callbackURL=http://my.server.com/bar

The callback URL will be invoked by the API method you're calling after it's done.

The callback URL can be set in the server configuration, database or passed as a parameter in the ruquest as above example.

Callbacks Usage

API Redirect: Redirecting the user to a different url after requesting API is succesful. Additional parameters can be added by API server to callback url
Avoid Polling: Requests can take time to respond. The client in this case need to poll the status api i.e. A GET request for response. So certain API can accept the request and use the callback API (callback url configured in database) later to give update on the earlier request.

How are callbacks different from APIs?

	API	Callback
Client	client requests the API url to get data	callbacks call the client url to send
Server	API Clients dont need a running server. They can request data when they want	Callback callback need active servers. They have to be active all the time accept connections.
Push	APIs cannot push data to other systems	callbacks can push data to a given url
Invoke	On API Request	On Event Trigger
request	Comes into the server	Goes out to callback URL
New data	Check repeatedly	Pushed to callback url

API callback url

callbacks are similar to APIs with respect to providing data to the clients. They can be built within the same API server. The user needs to provide a callback url, where they need the data send.

Setting up Callback reciever

Have a running server with a valid url publicly accessible
The URL should accept a POST request
URL should reply with a 201 response to let the Callback know that data has been sent correctly.

Registering the Callback url is a one time configuration activity that API user performs. The callback url from every user is different. So the API server can send data when available to different clients.

Steps to create Callback with API

Create an endpoint to accept Callback callback url for each user
Create a POST API request within the API server to callback url
Check for valid response from callback url and save response in database

How to get data from Callback API

The application recieving the callback gets information in the form of a request. A server can send data in GET or POST parameters in the callback request.

GET Request Example

https://mystore.example.com/callback?success=true&refId=3283191&

POST Request Example

https://mystore.example.com/callback
Content-Type: application/json

{
    "success":true,
    "refId":3283191
}

Both the above api callback examples send data in the form of request.

Response from API callback

In the above example, the application recieving the callback should respond back with an acknowledgement to the server issuing the callback, that it recieved the callback successfully. This completes the api callback cycle, and both parties exchange information. Along with acknowledgement, the callback api can send data in the response.

GET Request Example

https://mystore.example.com/callback?success=true&refId=3283191&

{
    "ack":true,
    "timestamp":"1644730268220",
    "reqRefId":"1292101282",
    "refId":"3283191"
}

Rest API callback

The above APIs are HTTP GET and POST rest api callbacks. They can use rest api status codes like 400, 422 to indicate invalid callback requests.

If the application is unable to process the callback request, it should return 500 Internal error. This is possible when too many callback requests are sent in a short interval and the application handling the request crashes.

For recieving multiple callbacks on a single identifer or reference number, request identifer in the rest api callback url can be used as follows.

https://mystore.example.com/callback/3283191?success=true