168

I've been scouring the net, and can't seem to wrap my head around the idea of a callback URL. In my case I have a few callback URLs that I have to define myself. A popular one is a "default callback URL". What is this exactly? Can you give an example in plain english?

General Grievance
  • 4,555
  • 31
  • 31
  • 45
ApathyBear
  • 9,057
  • 14
  • 56
  • 90

8 Answers8

120

A callback URL will be invoked by the API method you're calling after it's done. So if you call

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

Then when /foo is finished, it sends a request to http://my.server.com/bar. The contents and method of that request are going to vary - check the documentation for the API you're accessing.

Eric Stein
  • 13,209
  • 3
  • 37
  • 52
  • 1
    Would it cause an error if the callback URL is not set correctly? – user3768495 Feb 05 '16 at 00:34
  • @user3768495 I would expect it would not, but that's going to depend on the implementation of the API. It could, in theory, make the callback part of a transaction internally, and roll back any changes made by the original request if the callback doesn't return a 2xx response. – Eric Stein Feb 05 '16 at 02:50
  • Do I need to send a response to the POST request at /api.example.com/foo ? – Abhijeet Ahuja Jul 05 '16 at 01:51
  • @Abhijeet You never *need* to. If it's appropriate to include a response, yes, do so. – Eric Stein Jul 05 '16 at 13:53
  • similar question: https://stackoverflow.com/questions/28391359/what-is-callback-url-in-instagram-api-and-how-to-can-i-implement-it – Deke May 31 '18 at 15:42
  • How does an application make a callback url available to the API without opening up security holes, where anyone can access that callback url? wouldn't the API not be authenticated? – Emil Jul 11 '21 at 18:02
  • @Khatri - it's data that is given from the client to the server. So _both_ sides need to keep it (until they no longer need it). – Toby Speight Oct 23 '21 at 08:34
101

Think of it as a letter. Sometimes you get a letter, say asking you to fill in a form then return the form in a pre-addressed envelope which is in the original envelope that was housing the form.

Once you have finished filling the form in, you put it in the provided return envelope and send it back.

The callback URL is like that return envelope. You are basically saying, "I am sending you this data; once you are done with it, I am listening on this callback URL waiting your response." So the API will process the data you have sent then look at the callback to send you the response.

This is useful because sometimes you may take ages to process some data and it makes no sense to have the caller wait for a response. For example, say your API allows users to send documents to it and virus scan them. Then you send a report after. The scan could take maybe 3 minutes. The user cannot be waiting for 3 minutes. So you acknowledge that you got the document and let the caller get on with other business while you do the scan, then use the callback URL when done to tell them the result of the scan.

Toby Speight
  • 27,591
  • 48
  • 66
  • 103
Taf Munyurwa
  • 1,444
  • 2
  • 16
  • 22
34

If you use the callback URL, then the API can connect to the callback URL and send or receive some data. That means API can connect to you later (after API call).

Example

Diagram

  1. YOU send data using request to API
  2. API sends data using second request to YOU

Exact definition should be in API documentation.

jiwopene
  • 3,077
  • 17
  • 30
20

It's a mechanism to invoke an API in an asynchrounous way. The sequence is the following

  1. your app invokes the url, passing as parameter the callback url
  2. the api respond with a 20x http code (201 I guess, but refer to the api docs)
  3. the api works on your request for a certain amount of time
  4. the api invokes your app to give you the results, at the callback url address.

So you can invoke the api and tell your user the request is "processing" or "acquired" for example, and then update the status when you receive the response from the api.

Hope it makes sense. -G

Giuseppe B
  • 1,194
  • 8
  • 7
14

I'll make this pretty simple for you. When a transaction is initiated, it goes under processing stage until it reaches the terminal stage. Once it reaches the terminal stage, the transaction status is posted by the payment gateway to the callback url which generally the merchants use as a reference to show the success/failure page to the user. Hope this helps?

Swagat sahoo
  • 141
  • 1
  • 3
9

Another use case could be something like OAuth, it's may not be called by the API directly, instead the callback URL will be called by the browser after completing the authencation with the identity provider.

Normally after end user key in the username password, the identity service provider will trigger a browser redirect to your "callback" url with the temporary authroization code, e.g. 

https://example.com/callback?code=AUTHORIZATION_CODE

Then your application could use this authorization code to request a access token with the identity provider which has a much longer lifetime.

Hainan Zhao
  • 1,962
  • 19
  • 19
7

Here's a common example of how a callback works - something that most people who've bought online probably have experienced. You've made a purchase on your favorite website and clicked the "Submit" button. Chances are you'll be sent to an external service that handles the payment processing (like PayPal) where you confirm your order, or just wait while you watch the word "processing..." blink on the screen. After the transaction completes you are directed back to the original shopping site. The page that you see is the callback URL. Though you didn't know it, you left your favorite online store's website during the processing, and the external site you visited returned you back to it. Barring any glitches you should see the page the store wanted you to see after an order. It might be a thank you page, or other page with order confirmation information, next steps, or their home page. It may vary depending on what you ordered, when you ordered, and how you ordered.

Basically a callback URL gives directions to an external system on where to go next. What is at that URL could be anything. It doesn't have to be a static URL. More

Junta
  • 97
  • 2
  • 7
0

In the OAuth workflow, Callback URL would be the url to which the user will be redirected after authorisation from the OAuth provider. Like how 'Sign in with Google' takes you to a Google page and then sends you back to the app where you clicked the 'Sign in with Google' Button.

synner90
  • 1