External Service Integration using the Auphonic API

You can use the Auphonic API to integrate your service or app (podcast hosting company, audio publishing platform, video tool, file service, etc.) as an External Service within Auphonic. Then all Auphonic users will see your service at our External Services Page and will be able to reference it in any Production or Preset in the section Publishing / External Services:

Note

Your users will need an Auphonic account and all processing and billing is done using that account (you won’t have any costs)!
Please contact us if you want to use one Auphonic account for all of your users.

Overview

The integration consists of three steps and you don’t need to implement any API on your end to receive production metadata and media files on your servers.

Setup an Auphonic OAuth App
First you have to setup an Auphonic OAuth app to allow your users to associate their Auphonic account with your service/app.
Request to create an External Service for your Users
Use the External Service Creation Call to register your service/app as an external service for the given Auphonic user.
Your service/app will now show up in the user’s list of connected external services, thus allowing them to select it as a publishing target in the Publishing / External Services section of any production or preset.
Auphonic Webhook Call after a finished Production
If your service is added to a production, we will call a URL (webhook) on your server when it is finished and send you the UUID of the production.
You can use the UUID, together with the OAuth credentials of your user, to query all details about the production (metadata, stats, images, speech recognition results, etc.) and to download media result files.

Note

Please contact us if you have any problems or questions, we are happy to help you with the integration!

Detailed Integration Steps

1. OAuth App Setup

First you have to setup an Auphonic OAuth app to allow your users to associate their Auphonic account with your service/app:
OAuth 2.0 Authentication Flow for Web Apps
Upon completing the authentication flow you will receive an access token for each user granting access to their Auphonic API resources.

Once you have verified that your OAuth client setup is working please contact us and we will whitelist your app for registering as an external service within Auphonic.
Your app will still be hidden and is only intended for development at that stage.

2. External Service Creation Call

To create an external service account for one of your users, send a POST request in JSON format to the endpoint /api/service/connect.json:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {access_token_of_your_user}" \
    https://auphonic.com/api/service/connect.json \
    -d '{
            "display_name": "My Family Podcast",
            "webhook_url": "https://your-service.fm/userXY/webhook/aweouihreu/",
            "custom_data": "any-data-string-you-want",
        }'

The following parameters are available:

webhook_url :: The webhook URL on your server.
Will receive an HTTP request whenever the user finishes a production with your service selected as Publishing / External Service - for details on the format, please see 3.1 Webhook after a finished Production.
display_name :: The name of the specific service instance/show (for example: “My Family Podcast”, “My Insane Video Channel”, etc.).
Your company/app name (for example: “Podhoster 1”, “Video Hoster B”, etc.) should not be included here, it will be unconditionally prepended to the display_name on our side.
custom_data (optional):: Any custom string data (maybe JSON?) that you would like to receive back from us when we invoke the webhook after finishing a production.
Potential uses for this data include associating the production with a show/podcast in your system or limiting its publishing state to private/public/draft. Hence, you might create multiple connections to a specific show or podcast, with different behavior using a different display_name (for example: “My Family Podcast - Publish Now”, “My Family Podcast - Draft Episode”, etc.) and custom_data.

Note

If you call /api/service/connect.json for the same user and display_name multiple times, we won’t create a new service instance but update the parameters webhook_url and custom_data of the old instance instead!

Hint

If you don’t want an additional step to connect your service with Auphonic, you might call /api/service/connect.json automatically after the OAuth flow of a user.

3.1 Webhook after a finished Production

If your service is added in the Publishing / External Services section of a production, we will invoke your previously set webhook_url using a POST request in JSON format encoded using JSON Web Tokens (JWT).
We utilize the field client_secret of your OAuth client app to encode and sign the webhook parameters so that you can decode and verify them on your end.

The Auphonic webhook request behaves similarly to the following curl command:

curl -X POST -H "Content-Type: application/jwt" \
    https://your-service.fm/userXY/webhook/aweouihreu/ \
    -d 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1dWlkIjoiZGVpZ3R2RHY4akg2TmFLNTJaNWVYSCIsImN1c3RvbV9kYXRhIjoiYW55LWRhdGEtc3RyaW5nLXlvdS13YW50In0.Z-mg9ZcxBSWoBFa1JYuAW3ZDftNaH1yUHZS4VslfmCQ'

The request body is encoded using JWT with the HS256 signature algorithm and may be decoded and verified using any of the many JWT libraries for Token Signing/Verification available.
For example, using Python and PyJWT:

import jwt
data = jwt.decode(
    'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1dWlkIjoiZGVpZ3R2RHY4akg2TmFLNTJaNWVYSCIsImN1c3RvbV9kYXRhIjoiYW55LWRhdGEtc3RyaW5nLXlvdS13YW50In0.Z-mg9ZcxBSWoBFa1JYuAW3ZDftNaH1yUHZS4VslfmCQ',
    your_oauth_client_secret, algorithms=["HS256"]
)

print(data):
    {
        "uuid": "deigtvDv8jH6NaK52Z5eXH",
        "custom_data": "any-data-string-you-want"
    }

Body parameter description:

uuid :: The UUID of the finished production.
Should be used, together with the OAuth authentication (bearer) token of the associated user, to Request Details of the completed Production, and to download the result audio files.
If you are a podcast hosting service, we guarantee that there will at least one CBR MP3 output file available (amongst possible other formats). Please contact us in case you have any special requirements (videos, multiple audio formats, etc.).
custom_data (optional):: The contents of the custom_data field your provided in 2. External Service Creation Call.
As mentioned in the service creation call documentation, this might be useful for managing your internal associations.

3.2 Webhook JSON Response (optional)

If your webhook response does not return an HTTP success status code (200, 201, 203, 204) or takes too long, we will retry the webhook.
Additionally, you may return the following parameters in JSON format:

{
    "result_page_url": "https://your-service.fm/userXY/episode/50-my-new-episode",
    "result_file_url": "https://your-service.fm/userXY/files/50-my-new-episode.mp3"
}

Parameter description:

result_page_url (optional):: The URL of the published result page.
This could be the link to a created podcast episode, for instance: https://your-service.fm/userXY/episode/50-my-new-episode .
result_file_url (optional):: The URL to the published audio file on your server.
Example: https://your-service.fm/userXY/files/50-my-new-episode.mp3 .

Both JSON response parameters are optional, and we won’t display anything (nor show any error) if we do not receive them.
The webhook request timeout is 60s to ensure that you have enough time to reply.

Public Release of your External Service

Please contact us again when your integration is finished, so that we can feature your service on the External Services Page and in our External Services Help documentation.

Then all Auphonic users will be able to find your integration, and we are happy to announce it on our channels as well!