Callback URLs

Sometimes you make a remote call to an external application API and expect the application to call you back to one of your published APIs. This "call you back" is referred to as "callback". The callback can happen synchronously or asynchronously.

For example, a web-store calls a payment server to make a payment. The payment server may callback the web-store server in following ways:

• The payment server calls back the web-store even as the web-store is waiting for a response to its original payment request. This is a synchronous callback. This could be done for some security purpose, say, to check if the caller is trusted.
• The payment server calls back the web-store after responding to the original payment request. This is an asynchronous callback. This could be done to inform the web store that the payment has been cleared. Sometimes clearing a payment could take minutes or hours or even more.

Callback implementation becomes much simpler when the callback URL is passed in the original request. Consider the following request/response and an asynchronous callback:

Request:

https://payment-server.com/endpoint?caller=happy-store&amount=99&currency=USD

Response to the above request:

payment-id=1234&status=in-progress

When payment is cleared, say after an hour, payment-server looks up happy-store's URL (which is presumably registered somewhere in payment-server's configurations) and calls back happy-store's URL

https://happy-store.com/payment-status?payment-id=1234&status=completed

So what is the issue with this? It is development and testing issue. happy-store may have many servers: for development, QA, demo, staging, etc., all of which will have different URLs. If the QA server made the original payment request, the callback is expected to be to the QA server.

It becomes painful for payment-server to keep track of different servers from the same caller. Passing a callback URL in the original request helps.

https://payment-server.com/endpoint?caller=happy-store&amount=99&currency=USD&callback-server-base-url=http://qa.happy-store.com

Payment-server then constructs the callback URL based on the callback-server-base-url parameter. This requires the base url to be saved with each payment request. From our experience, it is easier, cleaner to implement that way instead of figuring out the URL based on from some other logic.

Not discussed here, but security implications of passing a callback URL should be thought through.