djctl

Webhook API

Overview

The djctl Webhook API provides a simple mechanism for providing real-time track transition updates to an HTTP or HTTPS endpoint.

Connection details

When launching djctl, use the --webhook.url command line parameter to configure an HTTP or HTTPS endpoint.

Event data

As a new track transitions into “featured” state, a JSON formatted message is sent as an HTTP POST to the defined webhook.url. The following is an example message:

{
  "artist": "Fred Falke",
  "title": "So Good",
  "genre": "Electronic",
  "art": "iVBORw0...[REDUCED]",
  "spotify_code": "iVBORaa...[REDUCED]",
  "duration": 235,
  "timestamp_epoch": 1644597789226,
  "timestamp": "2022-02-11T08:43:09.226786-08:00",
  "elapsed": "00:01:05"
}

Attribute dictionary

The following table enumerates default attributes found in the event JSON. Each of these attribute names can be customized in the JSON payload using the specified flag.

AttributeFlagTypeDescription
title--webhook.json.titlestringTrack title
artist--webhook.json.artiststringTrack artist
genre--webhook.json.genrestringTrack genre
art--webhook.json.artstringTrack album art as Base64 encoded PNG (RGB, 256x256)
spotify_code--webhook.json.spotifystringSpotify code image as Base64 encoded PNG
duration--webhook.json.durationintegerTotal track duration in seconds
timestamp--webhook.json.timestampstringTimestamp in format 2022-02-11T08:24:47.162918-08:00
timestamp_epoch--webhook.json.epochintegerUnix time; the number of seconds elapsed since January 1, 1970 UTC
elapsed--webhook.json.elapsedstringElapsed time since the first track triggered in format hh:mm:ss

Custom JSON messages

Using the attribute flags in the previous table, the Webhook JSON message can be customized. For example, to move all attributes under a top-level data key, the following flags can be supplied:

--webhook.json.title=data,title \
--webhook.json.artist=data,artist \
--webhook.json.genre=data,genre \
--webhook.json.art=data,art \
--webhook.json.spotify=data,spotify_code \
--webhook.json.duration=data,duration \
--webhook.json.timestamp=data,timestamp \
--webhook.json.epoch=data,timestamp_epoch \
--webhook.json.elapsed=data,elapsed

The following is equivalent configuration YAML.

webhook:
  json:
    artist: ["data", "artist"]
    title: ["data", "title"]
    genre: ["data", "genre"]
    art: ["data", "art"]
    spotify: ["data", "spotify_code"]
    duration: ["data", "duration"]
    timestamp: ["data", "timestamp"]
    epoch: ["data", "epoch_timestamp"]
    elapsed: ["data", "elapsed"]

The following is the resulting JSON message. Notice fields are now nested under the data key.

{
  "data": {
    "art": "iVBORw0KGgoAA...<redacted>",
    "artist": "Louis La Roche",
    "duration": 315,
    "epoch_timestamp": 1662141298,
    "genre": "Electronic",
    "spotify_code": "iVBORw0KGgoAAA...<redacted>",
    "timestamp": "2022-09-02T10:54:58.894612-07:00",
    "title": "Lovers",
    "elapsed": "00:01:05"
  }
}

Using Webhook JSON configuration flags, fields can also be omitted. The following flags remove album art and the Spotify code.

--webhook.json.art= \
--webhook.json.spotify=

The following is equivalent configuration YAML.

webhook:
  json:
    art: []
    spotify: []

The following is the resulting JSON message. Notice the art and spotify_code keys are not present.

{
  "artist": "Mylo",
  "duration": 289,
  "genre": "",
  "timestamp": "2022-09-02T11:03:00.758897-07:00",
  "timestamp_epoch": 1662141780,
  "title": "Lovers - Mylo Edit",
  "elapsed": "00:01:05"
}

Custom format string

An optional string field is available for inclusion in the JSON message using a combination of the --webhook.format and --webhook.json.format flags. The --webhook.format flag specifies a substitution variable string and the --webhook.json.format flag specifies the key path for this string in the Webhook JSON message.

The example flags below insert a custom field named summary and removes the default art and spotify_code fields from the JSON message. The contents of the summary field are derived using the --webhook.format string.

--webhook.format="\$TIMESTAMP_YEAR\$/\$TIMESTAMP_MONTH\$/\$TIMESTAMP_DAY\$ - \$TIMESTAMP_HOUR\$:\$TIMESTAMP_MINUTE\$:\$TIMESTAMP_SECOND\$ - \$ARTIST\$ - \$SONG\$" \
--webhook.json.format=summary \
--webhook.json.art= \
--webhook.json.spotify=

The following is an equivalent YAML configuration.

webhook:
  format: "$TIMESTAMP_YEAR$/$TIMESTAMP_MONTH$/$TIMESTAMP_DAY$ - $TIMESTAMP_HOUR$:$TIMESTAMP_MINUTE$:$TIMESTAMP_SECOND$ - $ARTIST$ - $SONG$"
  json:
    art: []
    spotify: []
    format: ["summary"]

The following is the resulting JSON message.

{
  "artist": "Loleatta Holloway",
  "duration": 453,
  "genre": "",
  "summary": "2022/09/02 - 11:37:29 - Loleatta Holloway - Love Sensation (Dimitri from Paris DJ Friendly Classic Re-Edit) - 2017 - Remaster",
  "timestamp": "2022-09-02T11:37:29.613794-07:00",
  "timestamp_epoch": 1662143849,
  "title": "Love Sensation (Dimitri from Paris DJ Friendly Classic Re-Edit) - 2017 - Remaster",
  "elapsed": "00:01:05"
}
Prev
CLI
Next
WebSocket API