Custom Listener Authentication Webhook

Custom Listener Authentication allows you make your audio stream private and accessible only to authorized listeners. When a listener connects to your stream, Radio Mast will make an HTTP request (or "webhook") to a URL of your choice, and based on the response from that URL, the listener will be allowed or denied access. This allows you to integrate your own authentication system, giving you flexibility over how you authenticate listeners.

Custom Listener Authentication is included in all Radio Mast streaming plans.

In a hurry? Code samples for PHP and Python are available on Github.

Table of Contents

Configuring Custom Listener Authentication

After logging into Radio Mast:

  1. Click Streams on the left.
  2. Click the stream you'd like to configure.
  3. Select the Configuration tab.
  4. Under Listener Authentication, click Custom. Enter the URL of your authentication service (see below).
  5. Click Save Stream to apply your settings.

Webhook Specification

Listener authentication is performed using HTTP POST requests. When a listener connects, Radio Mast will make an HTTP POST request to your custom listener authentication URL. Based on the response from the request, the listener will then either be allowed to connect or be rejected. A denied listener will receive a HTTP 401 Unauthorized response.

Both HTTP and HTTPS webhook URLs are supported.

To authorize the listener, the HTTP header icecast-auth-user: 1 must be provided in your response. If this header is not found, the listener will be denied with an HTTP 401 Unauthorized response.

Parameters for the HTTP POST request are URL encoded as regular form data, not JSON encoded. The Content-Type is application/x-www-form-urlencoded.

The parameters included with the HTTP POST request for Listener Authentication are as following:

POST Parameters:
  • action - This will be listener_add.
  • mount - The URL path the listener is connecting to, including any query string. (eg. /mystream?token=1234)
  • server - The local IP of the Radio Mast streaming edge server.
  • port - The port the listener is connecting to.
  • ip - The IP of the listener.
  • user - The username provided by the listener, if any. (via HTTP Basic Authentication).
  • pass - The password provided by the listener, if any.
  • client - A unique 64-bit integer that identifies this listener for the duration of the connection.
  • agent - The HTTP user-agent header provided by the listener.
  • referrer - The HTTP referrer header provided by the listener.
  • listener-count - The current listener count to the stream, excluding the pending new listener.
  • listener-duration-1day - The cumulative listening time (in seconds) of this listener on this stream over the last 24 hours.
  • listener-duration-7day - The cumulative listening time (in seconds) of this listener on this stream over the last 7 days.


To authenticate listeners, we recommend generating unique security tokens for each user that expire after a few hours. Append this token to your stream URL as a query string parameter and validate it in your authentication backend.

For example, if you were to generate and store the unique token "12345" for a given user, you could append this to the stream URL provided to the user, like this:

When the connects to your stream, Radio Mast will make an HTTP POST request to your server. The mount POST parameter would contain the value 9fc0077d-ab22-4f8b-b249-94f4bc65996b?token=12345, from which the token could be parsed. Your backend would then verify that token 12345 is valid at the current time.

Monitoring Authenticated Streams

Radio Mast Stream Monitoring is able to perform basic monitoring your authenticated stream to determine if the stream is up. However, silence detection is unavailable as Stream Monitoring is unaware of any extra parameters needed to authenticate with your stream.

As a workaround, your authentication webhook backend could be configured with a special security token to be used with monitoring only. You can then set up monitoring on a separate stream URL that includes this special security token.

For example, your backend could try to ensure this URL passes authentication:


Custom webhook authentication can be used to impose a time limit on each listener session. After the time limit, Radio Mast will disconnect the listener.

You can specify a time limit for a listener session by setting the icecast-auth-timelimit header in your response to a maximum duration in seconds. For example, if your response includes icecast-auth-timelimit: 3600, the listener would be kicked after 1 hour.

A full HTTP response from your webhook URL to allow a listener but limit them to 1 hour of listening would look like:

HTTP/1.1 200 OK
icecast-auth-user: 1
icecast-auth-timelimit: 3600
Connection: close

Most players will attempt to automatically reconnect after a connection drops. You can prevent the listener from reconnecting by denying the subsequent webhook by returning the icecast-auth-user: 0 header.


When denying a listener (with icecast-auth-user: 0), you can redirect the user to an alternative URL. This is useful for playing a announcement explaining why the listener is not allowed to connect.

You can redirect a listener by setting the icecast-auth-redirect header to a URL containing other audio. This URL can be a static file or another live stream. Radio Mast will redirect the listener to the specified URL instead of allowing the listener to connect.

For example, you could redirect a denied listener to an MP3 file:


or redirect the listener to a lower quality stream:


Dynamic Custom Ads

A custom preroll or postroll ad can be inserted dynamically in your stream by including one of the following HTTP headers in your response:

  • preroll: <url>
  • postroll: <url>

Note that the postroll header must be used with a timelimit (icecast-auth-timelimit: <seconds>).

Dynamic Custom Ads allow you to play different ads for different listeners.

The URL specified for any Dynamic Custom Ad must contain an audio file matching the audio format of your stream. In particular, the codec, bitrate, channel count, and samplerate must match. Files up to 5 MB in size are supported. For more information, see Custom Ads.

Note on AAC Dynamic Custom Ads

Dynamic Custom Ads for AAC streams must be encapsulated in ADTS containers, which are different from the MPEG-4 (.m4a) containers used by most AAC audio files. This is because ADTS is the standard for online AAC streams.

To convert an audio file to be an ADTS-encapsulated AAC file, we recommend using FFMPEG. The following command will convert an audio file (input.wav) to this format:

ffmpeg input.wav -b:a 128k output.aac

For HE-AAC v1 and HE-AAC v2 (AAC+) streams, please make sure your ad files are in the same format.


There are a number of technical requirements necessary for Dynamic Custom Ads to work correctly. Some of these have already been covered in the above sections.

  • The audio format of an ad file must match the stream.
  • Ads should be served by a webserver that supplies the ETag header, for optimal caching behaviour. Most webservers will do this automatically, including popular file hosting services and CDNs such as AWS S3 and CloudFront.
  • Ad files must be less than 5 MB in size.

Caching Behaviour

To conserve bandwidth, the Radio Mast Streaming Network will cache your dynamic ads based on the ETag header supplied by your webserver when they are downloaded. Ad files may be cached for up to 2 hours, after which the ETag at the original URL will be checked again to validate if the upstream file has changed.

Example: Limiting Weekly Listening

This is a high level example for developers explaining how to implement cumulative time limits for listeners using the listener authentication webhook.

When a listener connects to your stream, a webhook will be POSTed to your custom listener authentication URL. When handling this POST request, you would write code to:

  • Read the listener-duration-7day POST variable to determine the cumulative listening time of the listener over the last 7 days. (See Webhook Specification.)
  • If the listener exceeded your desired weekly time limit, you would deny the listener and redirect them to an announcement by setting the icecast-auth-user: 0 header and the icecast-auth-redirect to the URL of an MP3 file with your announcement. (See Redirection.) For example, your announcement could ask users to upgrade to a premium account to continue listening.
  • You can impose a timelimit directly on the listener session including the icecast-auth-timelimit: <secs> header in your response.
  • If you do impose a timelimit, you can also supply a custom postroll ad to play once the listener hits the timelimit, by including postroll: <url> in your response.

See the Code Samples below for a concrete example of how to build a webhook handler.

Code Samples

Example listener authentication webhook handlers in PHP and Python are available on Github.