Project Callbacks

When respondents record a video or an audio response and the Response record is created on our platform, we get to work converting a simple video to something that brings value to our customers. Transcoding, transcribing, translating, sentiment-analysis gathering all take real time, so we built in webhook support into our platform, allowing us to notify your platform when noteworthy events happen on a Response.

Callbacks are set on Projects, so when a new Response is created on that Project, or something happens on an already existing Response inside a Project that has a callback URL setup, we’ll send a POST request to your callback URL.

The request payload is a set of states all Responses have (see POST /v2/question for a full list of states). States allow you to act when Responses are fully or partially realised. As the callback will be called every time one of the states change, we recommend ignoring or not persisting the Response, at least until the Response has an approved transcript, because there’s still a possibility that the user may choose to re-record their Response, or we're making some final adjustments to it.

Setting Callback URL

You can set the Callback URL by specifying the callback_url parameter when you’re creating Projects (see POST /v2/question), or at anypoint after (see PUT /v2/question/{questionId}).

Merge Fields

Callbacks provide a way to inject Additional Data fields into your Callback URL with the help of Merge Fields. You can specify multiple Merge Fields, either as Path or Query parameters. This allows you to easily identify the Response the callback is referencing. 

A common use case of Merge Fields is to link a Response with a response from a survey platform. If the survey platform’s response ID has been stored as Additional Data on the video Response, and if you’ve set that ID as a Merge Field on the incoming callback, you will immediately know the survey response our video Response is referencing.

To make use of Merge Fields, set a path or query parameter of your callback to be equal to {{additional_data_key}}, where the name of your Additional Data field is between {{ and }}.

Like so - https://api.your-domain.com/voxpopme/survey/{{surveyId}}/callback?response={{responseId}}

Inside the payload of the callback you will also be able to find our own Response ID. If you store our Response ID, you’ll be able to easily get all of the Response data, or a set of Responses using an ”in” filter. More about fetching and filtering Responses in the ‘Getting Responses’.

Callback Authentication

For added security, all callbacks can be sent with your chosen API token inside the request’s header, please see PUT /v2/account/{accountId}/callback-authentication in the public API documentation.

Manually Triggering Callbacks

As callbacks are normally triggered by changes on the responses, you can manually re-triggered callbacks on your projects by simply editing the transcript on a chosen response, or by modifying any of the additional data fields.