Callback API

Metamug
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


Comments

Post a comment
Icon For Arrow-up