Webhook Integration

My Media for Alexa can notify an external HTTP endpoint whenever key playback events occur. This lets you integrate My Media with home automation systems, dashboards, logging tools, or any service that can receive an HTTP POST request.

Setting Up a Webhook

1. Navigate to Settings → General in the My Media Web Console.
2. Scroll to the Webhook section.
3. Enter a full http:// or https:// URL in the field (e.g. https://automation.example.com/hooks/mymedia).
4. Click Set.

Leave the field empty to disable webhooks entirely.

Payload Format

Every webhook call is an HTTP POST request with a Content-Type: application/json header.

All payloads share the same top-level envelope:

{
  "event": "<event_name>",
  "timestamp": "<ISO 8601 UTC datetime>",
  "data": { ... }
}

Event Reference

playlist_start

Fired when a playlist has been created and is about to be handed to Alexa for playback. This is the earliest point at which you know what will play.

data fields:

Example:

{
  "event": "playlist_start",
  "timestamp": "2026-04-19T10:32:11.457Z",
  "data": {
    "playlist": "Rock Classics",
    "track_count": 43
  }
}

track_start

Fired each time Alexa begins streaming a track (i.e. audio playback has actually started on the device).

data fields:

Example:

{
  "event": "track_start",
  "timestamp": "2026-04-19T10:32:14.801Z",
  "data": {
    "track": "Bohemian Rhapsody",
    "artist": "Queen",
    "album": "A Night at the Opera",
    "genre": "Rock",
    "playlist": "Rock Classics",
    "device": "Living Room Echo",
    "artwork_url": "http://192.168.1.10:52199/thumbnail?mediaitem=1234"
  }
}

track_paused

Fired when the user pauses playback (e.g. "Alexa, pause").

data fields:

Example:

{
  "event": "track_paused",
  "timestamp": "2026-04-19T10:34:02.123Z",
  "data": {
    "track": "Bohemian Rhapsody",
    "artist": "Queen",
    "album": "A Night at the Opera",
    "genre": "Rock",
    "playlist": "Rock Classics",
    "artwork_url": "http://192.168.1.10:52199/thumbnail?mediaitem=1234"
  }
}

track_stopped

Fired when the user explicitly stops playback (e.g. "Alexa, stop").

data fields:

Example:

{
  "event": "track_stopped",
  "timestamp": "2026-04-19T10:41:55.900Z",
  "data": {
    "track": "Bohemian Rhapsody",
    "artist": "Queen",
    "album": "A Night at the Opera",
    "genre": "Rock",
    "playlist": "Rock Classics",
    "artwork_url": "http://192.168.1.10:52199/thumbnail?mediaitem=1234"
  }
}

track_failed

Fired when Alexa reports that it could not stream a track (e.g. a network error, unsupported codec without transcoding enabled, or firewall blocking the connection).

data fields:

Example:

{
  "event": "track_failed",
  "timestamp": "2026-04-19T10:33:01.200Z",
  "data": {
    "track": "In The Air Tonight",
    "artist": "Phil Collins",
    "album": "Face Value",
    "genre": "Pop",
    "error_code": "MEDIA_ERROR_UNKNOWN",
    "artwork_url": "http://192.168.1.10:52199/thumbnail?mediaitem=5678"
  }
}

track_finished

Fired when Alexa completes playing a track naturally (i.e. it reaches the end and the next track is being requested). This event fires for every track that plays to completion — use it to record play history or update a "last played" indicator.

data fields:

Example:

{
  "event": "track_finished",
  "timestamp": "2026-04-19T10:34:55.312Z",
  "data": {
    "track": "Bohemian Rhapsody",
    "artist": "Queen",
    "album": "A Night at the Opera",
    "genre": "Rock",
    "artwork_url": "http://192.168.1.10:52199/thumbnail?mediaitem=1234"
  }
}

playlist_finished

Fired when a playlist reaches its end and looping is off — i.e. there are no more tracks to play. This event does not fire if the user manually stops playback; use track_stopped for that.

data fields:

Example:

{
  "event": "playlist_finished",
  "timestamp": "2026-04-19T11:05:42.000Z",
  "data": {
    "playlist": "Rock Classics"
  }
}

Behaviour and Reliability

Because webhooks are fire-and-forget, a slow or unavailable endpoint will never delay or interrupt audio playback.

Example: Home Assistant

The following is an example Home Assistant REST command trigger that could be used to react to a track_start event (configured on the Home Assistant side to listen for the incoming POST):

# In configuration.yaml
input_text:
  now_playing:
    name: Now Playing

Your receiving endpoint would parse the JSON body, extract data.track and data.artist, and update the input_text entity via the Home Assistant WebSocket API or REST API accordingly.

Troubleshooting

My webhook URL is being rejected in the Settings page

The URL must start with http:// or https://. Relative URLs, bare hostnames, and localhost without a scheme are not accepted.

I'm not receiving webhook calls

1. Check that the URL is reachable from the machine running My Media (not just your browser machine).
2. Check the My Media log (available on the Support screen) for Webhook error entries.
3. Ensure your endpoint responds within 3 seconds — requests that take longer are abandoned.
4. Verify your endpoint accepts POST requests with a Content-Type: application/json body.