# Webhook API<no value>

## 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:

```json
{
  "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.

| Attribute | Flag | Type | Description |
|-----------|------|------|-------------|
| title | `--webhook.json.title` | string | Track title |
| artist | `--webhook.json.artist` | string | Track artist |
| genre | `--webhook.json.genre` | string | Track genre |
| art | `--webhook.json.art` | string | Track album art as Base64 encoded PNG (RGB, 256x256) |
| spotify_code | `--webhook.json.spotify` | string | Spotify code image as Base64 encoded PNG |
| duration | `--webhook.json.duration` | integer | Total track duration in seconds |
| timestamp | `--webhook.json.timestamp` | string | Timestamp in format 2022-02-11T08:24:47.162918-08:00 |
| timestamp_epoch | `--webhook.json.epoch` | integer | Unix time; the number of seconds elapsed since January 1, 1970 UTC |
| elapsed | `--webhook.json.elapsed` | string | Elapsed time since the first track triggered in format hh:mm:ss |
{.table-striped}

## 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:

```text
--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.

```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.

```json
{
  "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.

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

The following is equivalent configuration YAML.

```yaml
webhook:
  json:
    art: []
    spotify: []
```

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

```json
{
  "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](/docs/reference/cli/#substitution-variables) 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.

```text
--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.

```yaml
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.

```json
{
  "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"
}
```