Webhooks

The Auphonic API allows users to define custom URIs on their own servers as Webhooks.

Webhooks are HTTP POST callbacks to automate the interaction with Auphonic: after the processing of an audio file is finished, Auphonic calls the assigned URI with an HTTP POST request and all necessary status information about the production. This callback can be used to automate consecutive steps after Auphonic processing on your server or in your custom workflow.

To enable a webhook, just add the webhook parameter while creating or editing a production or a preset, as described in the following sections.

Add a Webhook to a Production

To create a new production with webhook, set the paramter webhook in the json data to a callback URI on your server:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/productions.json \
    -u username:password \
    -d '{
            "preset": "iWfe3DUoKLFxF7pJzoq5qa",
            "input_file": "http://auphonic.com/media/audio-examples/auphonic-dehum-unprocessed.m4a",
            "metadata": {"title": "Production with Webhook"},
            "webhook": "https://your-server.com/callback"
        }'

After the production is finished, Auphonic automatically calls the given URI with an HTTP POST request, please see Auphonic Webhook Request Details.

You can also add a webhook to an existing production:

curl -H "Content-Type: application/json" -X POST \
    https://auphonic.com/api/production/{uuid}.json \
    -u username:password \
    -d '{"webhook": "https://your-server.com/callback"}'

Or set the webhook using the Auphonic Simple API as well:

curl -X POST https://auphonic.com/api/simple/productions.json \
    -u username:password \
    -F "preset=ceigtvDv8jH6NaK52Z5eXH" \
    -F "title=Production with Webhook" \
    -F "input_file=@/home/user/your_audio_or_video_file.mp3" \
    -F "webhook=https://example.com/auphonic/webhook" \
    -F "action=start"

Auphonic Webhook Request Details

After the production is finished, Auphonic automatically calls your Webhook URI using an HTTP POST request in application/x-www-form-urlencoded or multipart/form-data format.

The following parameters are sent:

uuid: the uuid of your production (should be used to query further details about the production, see Query Details about a Production)
status_string: the status of your production, either Done or Error
status: the number that indicates a certain status, either 3 for Done or 2 for Error (see Query Production Status)

Auphonic tries to call your Webhook URI multiple times, sending the parameters in different formats:

Request 1: application/x-www-form-urlencoded

First we try an HTTP POST request in application/x-www-form-urlencoded format:

# Example curl command to simulate the Auphonic webhook
curl -X POST https://your-web-hook.com/endpoint -d "status=3&status_string=Done&uuid=zeigtvDv8jH6NaK52Z5eXH"

# request format on your server:
POST / HTTP/1.1
Host: https://your-web-hook.com/endpoint
User-Agent: curl/7.47.0
Accept: */*
Content-Length: 55
Content-Type: application/x-www-form-urlencoded

status=3&status_string=Done&uuid=zeigtvDv8jH6NaK52Z5eXH

We will retry this request if there is a timeout.

Request 2: multipart/form-data

If the application/x-www-form-urlencoded request fails (HTTP status 4xx, 5xx, etc.), we will try an HTTP POST request in multipart/form-data format:

# Example curl command to simulate the 2. request
curl -X POST https://your-web-hook.com/endpoint -F "status=3" -F "status_string=Done" -F "uuid=zeigtvDv8jH6NaK52Z5eXH"

# request format on your server:
POST / HTTP/1.1
Host: https://your-web-hook.com/endpoint
User-Agent: curl/7.47.0
Accept: */*
Content-Length: 363
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------ed2bcd1151f36973

--------------------------ed2bcd1151f36973
Content-Disposition: form-data; name="status"

3
--------------------------ed2bcd1151f36973
Content-Disposition: form-data; name="status_string"

Done
--------------------------ed2bcd1151f36973
Content-Disposition: form-data; name="uuid"

zeigtvDv8jH6NaK52Z5eXH
--------------------------ed2bcd1151f36973--

Add a Webhook to a Preset

To create a new preset with webhook, add the parameter webhook to the json request data:

curl -X POST -H "Content-Type: application/json" \
    https://auphonic.com/api/presets.json \
    -u username:password \
    -d '{
            "preset_name": "Preset with Webhook",
            "output_files": [{"format": "mp3"}],
            "webhook": "https://your-server.com/callback"
        }'

Productions which are created using this preset, will call the webhook automatically.

It’s also possible to add a webhook to an existing preset:

curl -H "Content-Type: application/json" -X POST \
    https://auphonic.com/api/preset/{uuid}.json \
    -u username:password \
    -d '{"webhook": "http://your-server.com/callback"}'

Delete a Webhook

To delete a webhook, create a production or presest edit request with an empty webhook parameter:

curl -H "Content-Type: application/json" -X POST \
    https://auphonic.com/api/{production|preset}/{uuid}.json \
    -u username:password \
    -d '{"webhook": ""}'