Webhook

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.

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"
}