V-Spark Online Help

Example Callback Server

In REST applications, a callback is the address and (optionally) the method name and parameters of a web application that can receive data via HTTP. Callbacks are typically used to enable another application to receive and directly interact with the transcripts produced by V‑Spark.

This section provides an example of setting up a simple callback server, submitting a sample audio file for transcription using the V‑Spark/transcribe  method, and then examining the results that are received by the callback server. This section concludes with suggestions for troubleshooting common problems when setting up and using a callback server.

Setting up a Sample Callback Server

To follow this example, you must have a callback server running on a given host and port. If you do not already have a callback server, the easiest way to simulate a callback server is to use the netcat application to listen on a specified port and display the information that it receives. The netcat application is a computer networking utility for reading from and writing to network connections using the TCP or UDP protocols. The name of its executable version is typically nc or nc.exe, depending on the operating system that you are using. The netcat utility is included in most Linux distributions and is freely available for most modern operating systems.

The sample output shown later in this section was produced by netcat  that was started using the following Linux command-line command:

while true ; do nc -l 5555 -k ; done

The trivial callback server that we are implementing here with the netcat command continually executes the netcat command, listening on port 5555 (the -l  option), and keeps its connections alive by listening for another connection after its current connection is completed (the -k  option). It does not have to generically return any values to applications that talk to that callback server because V‑Spark either expects an HTTP return code of success or only retries a limited number of times (100, by default) before canceling the callback.

Submitting a Sample File for Text Transcription

The following command calls the V‑Spark API, specifies the address of the callback server, specifies that you want text format output, and identifies the audio file that you want to transcribe:

curl -F callback=http://www.example.com:5555 \
      -F token=123e4567e89b12d3a456426655440000 \
      -F output=text -F "file=@sample7.wav;type=audio/wav" \

This sample command sends a text transcript of the audio file sample7.wav to the callback server.

Note that the sample audio file used in this example is a mono audio file, so the different portions of the audio in which voices are active (known as utterances) are separated by newlines.

Receiving Transcription Results

A callback server is generally used to collect output and forward it to some other application, process the transcript itself, or perhaps simply to preserve the output for subsequent use. Using the sample callback server that was introduced earlier, transcripts are written to the standard output for the shell in which you executed the netcat command.

As discussed earlier, the goal of a callback server is to enable another application to receive and directly interact with the transcriptions produced by V‑Spark. However, a simple callback server such as the one used in this section can also be convenient when testing the effects of trying different options with calls to V‑Spark's /transcribe  method.

Troubleshooting a Callback Server

If files are being uploaded successfully to V‑Spark, you received a success code (HTTP code 200) and a requestid in response to uploading to V‑Spark. If your callback server is not receiving results, check the items in the following list:

  • Verify that external hosts can reach your callback server - Receiving a success code and requestid in response to POSTing a request to V‑Spark shows that the system that is POSTing the request can reach V‑Spark. This does not mean that V‑Spark can reach your callback host. This lack of reachability is usually due to firewall or network connectivity restrictions.

    Verifying connectivity can most easily be done using a simple callback server like the one that was discussed in Setting up a Sample Callback Server.

    To test connectivity between V‑Spark and your callback server, log in on a host that is not on your local network and can be reached directly from the Internet. Once you are logged in there, attempt to reach the host on which your callback server is running. The following is a sample curl command that simply probes the URL at which a callback server is listening:

    curl -i http://host:5555

    The host and port that you specify are the host and port on which your callback server is listening.

    The -i option tells the curl command to display the HTTP header that it receives. For example, if you are using the sample callback server that was discussed earlier, you will receive a result that is something like the following:

    HTTP/1.1 200 OK


    If your network administration policies restrict inbound connectivity from external hosts, contact for the list of V‑Spark IP addresses from which access needs to be allowed.

  • Identify problems in your callback server - If you are able to reach the host and port on which your callback server is running from some other host on the Internet, connectivity is not the problem. Try the following steps to identify problems with your callback server:

    • Verify that you can POST directly to your callback server - use a command like the following to simulate the data that would be sent by V‑Spark to your callback server:

      curl -F "file=@test.json;type=application/json" \
           -F requestid=700e7496-4fce-4963-aa7b-b3b26600f813 \

      This command provides the two fields of the multipart POST that your callback server needs to be able to handle. Ensure that your callback server correctly returns success (HTTP code 200) when these two fields are received.

    • Verify correct error handling - it is possible for V‑Spark transcription to encounter an error. In such cases, an error message will be POSTed in an error field to your callback server. Your callback server must be able to handle receiving error messages from V‑Spark. The following example command sends the error message This is a sample error  to your callback server:

      curl -F "error=This is a sample error" \
           -F requestid=700e7496-4fce-4963-aa7b-b3b26600f813 \

      This sample command should trigger error handling in your callback server, such as logging a message.

If you still cannot identify or resolve the problem with your callback server, contact for assistance in diagnosing the problem that you are experiencing.