Blog

Developer
Concepts
Use Cases
Product
Spotlight

Receiving Job Status Updates with WebHooks for Symbl.ai

Symbl.ai’s Async API’s provide a REST interface that helps you to submit any recorded or saved conversations to Symbl.ai. When you submit a conversation, you’ll receive a Conversation ID unique to your conversation, and a unique Job ID which can be used to determine status and completion of Symbl.ai’s asyncronous conversation processing. Retrieving a job status can be accomplished either manually using the GET /job-status endpoint, or by passing a webhookUrl parameter in the initial async POST request in order to receive automatic job updates. This blog will focus on best practices for configuring webhooks.

Sign up

The first step to exploring the differences is to register for an account at Symbl (i.e., https://platform.symbl.ai/). Grab both your appId and your appSecret.

Authenticate

With both your appId and your appSecret you authenticate either with a cURL command or with Postman so that you receive your token. Here is an example with cURL`:

curl -k -X POST "https://api.symbl.ai/oauth2/token:generate" \\
     -H "accept: application/json" \\
     -H "Content-Type: application/json" \\
     -d "{ \\"type\\": \\"application\\", \\"appId\\": \\"<appId>\\", \\"appSecret\\": \\"<appSecret>\\"}"

After authenticating you receive your token, which will can be used to authorize requests Async API endpoints as Bearer Authorization.

Ideally a token server would handle authentication (with code that makes RESTful API call for generating token) so that neither the appSecret nor the appId were ever exposed. However, cURL sets you up immediately anyway. With the Bearer token handy you are now ready to establish a WebSocket endpoint for performing live transcription.

Webhooks Expected Response

For each specific job you will receive three status update webhook requests, each containing the Job ID they pertain to. These are:

  • scheduled – notice that your request has been received and is being prepped for processing.
{
id: '',
status: 'scheduled'
}
  • in_progress – notice that Symbl.ai is processing your conversation to generate a transcript and insights.
{
id: '',
status: 'in_progress'
}
  • completed – notice that the job has been completed, and you are free to make additional requests to the Conversation API for retrieveal of the job output.
{
id: '',
status: 'completed'
}

The webhookUrl Parameter

For requests to the Async API the webhookUrl parameter should be passed as a query param for requests containing local files, and in the body of the request for submissions providing the file contents via URL. For example, here is a sample cURL request using the Async Audio API endpoint.

curl --location --request POST 'https://api.symbl.ai/v1/process/audio/url' \\
--header 'Content-Type: application/json' \\
--header 'Authorization: Bearer $ACCESS_TOKEN' \\
--data-raw '{
"url": "https://link-to-storage.com/test-file.mp3",
"webhookUrl": "https://webhook-sample.com/symbl"
}'

Response:

{
"conversationId": "<conversationId>",
"jobId": "<jobId>"
}

Webhooks Server Configuration

There are two main requirements for a webhook server to be compatible with Symbl’s API’s:

1. The url must be publicly accessible.

2. The server must respond with either a status 200 or 201 upon receipt of successful POST requests. It is best practice to have the server respond immediately, before any other application logic to avoid unnecessary retries. See sample implementation below for an example.

Webhooks Server Sample Implementation

This is a sample implementation of a simple Node.js server using Express to listen over localhost. In this sample we’ll use ngrok to provide a HTTP tunnel to your localhost port.

// Require express and body-parser
const express = require('express');
const bodyParser = require('body-parser')
 
// Init and define a port
const app = express();
const PORT = 8000
 
// Let express know to use body-parsers JSON parser option
app.use(bodyParser.json())
 
// Start express at PORT
app.listen(PORT, () => console.log(`Listening at port ${PORT}`));
 
// Handle POST to your express server
app.post('/',(request,response) => {
// Send status 200 (or 201) response quickly to avoid retry
response.sendStatus(200);
 
// Handle job status request
let data = request.body;
console.log('jobId',data.id,' status:', data.status);
 
if (data.status === 'completed') {
console.log(`status is complete for jobId:${data.id}`)
//logic for handling completed job here
}
 
if (data.status === 'failed') {
console.log(`status is complete for jobId:${data.id}`)
//logic for handling failed job here
}
})

Once the Express server is booted up and listening, start ngrok with the terminal command:

$ ./ngrok http 8000

ngrok will provide a forwarding url exposing your localhost as an external url, which will be used as the webhookUrl parameter in your request to Symbl’s Async API.

ngrok by @inconshreveable                                                            (Ctrl+C to quit)

Session Status                online
Session Expires               1 hour, 57 minutes
Update                        update available (version 2.3.40, Ctrl-U to update)
Version                       2.3.35
Region                        United States (us)
Web Interface                 http://128.0.0.1:5051
Forwarding                    http://.ngrok.io -> http://localhost:8000
Forwarding                    https://.ngrok.io -> http://localhost:8000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Once a request is submitted to the Async API, you will see the webhook requests appear as console output from the node.js Express server, as well as in the ngrok terminal.

What’s Next

When a status: ‘completed’ event is received the conversation transcript & insights will be available via the Conversation API. Use the Conversation ID returned in the initial Async API request for retrieval. For full automation of this process additional logic can be added to the node.js Express server to handle these requests to the Conversation API upon job completion.

Join Our Community

Symbl.ai‘s invites developers to reach out to us via email at developer@symbl.ai, join our Slack channels, participate in our hackathons, fork our Postman public workspace, or git clone our repos at Symbl.ai’s GitHub.