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, eitherDone
orError
status
: the number that indicates a certain status, either 3 forDone
or 2 forError
(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 inmultipart/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": ""}'