Webhooks

Send automatic notifications to external services when events occur in your station.

What Is a Webhook

A webhook sends an HTTP POST request to a URL when a specific event occurs. External services can receive these notifications and take action.

Event occurs → xtra sends POST request → External service receives data

Available Triggers

Trigger	Event	Description
station.studio.newtrack	New track plays	Fires when a new track starts playing in the studio. Payload includes current and next track metadata.
station.encoder.statuschange	Encoder status change	Fires when an encoder connects or disconnects.

Plan Limits

The number of webhooks per station depends on the plan.

Plan	Webhooks per station
Plus	1
Pro	2
Ultimate	3
Enterprise	Custom

See Billing for plan details.

Adding a Webhook

1. Open Webhooks in the station sidebar
2. Click Add Webhook
3. Enter a name and destination URL
4. Select one or more trigger events
5. Click Save

Configuration Fields

Field	Description
Name	Display name for the webhook
URL	The endpoint that receives POST requests
Triggers	Array of events that activate the webhook

A webhook can listen to multiple triggers simultaneously.

Payload Format

Webhooks send JSON data in the POST request body. The payload structure depends on the trigger event.

The station.studio.newtrack payload includes artist, title, album, and cover URL for both the now-playing track and the next track.

{
  "trigger": "station.studio.newtrack",
  "nowPlaying": {
    "artist": "Artist Name",
    "title": "Track Title",
    "album": "Album Name",
    "cover": "https://static.xtra.audio/covers/example.jpg"
  },
  "next": {
    "artist": "Next Artist",
    "title": "Next Title",
    "album": "Next Album",
    "cover": "https://static.xtra.audio/covers/next.jpg"
  }
}

TIP

Use webhook.site to inspect the exact payload format during testing.

Testing Webhooks

Each webhook has a test button that sends a sample payload to the configured URL. Use it to confirm the endpoint receives requests without waiting for a live event.

1. Open Webhooks in the station sidebar
2. Locate the webhook to test
3. Click the test button
4. Confirm the sample payload arrives at the destination

To inspect the payload format with an external tool:

1. Visit webhook.site and copy your unique URL
2. Add the URL as a webhook in xtra audio
3. Trigger the event (play a track or toggle an encoder)
4. View the received payload on webhook.site

Use Cases

Integration	Trigger	Action
Discord	station.studio.newtrack	Post now-playing to channel
Website widget	station.studio.newtrack	Update live track display
Monitoring	station.encoder.statuschange	Alert on encoder disconnect
Analytics	station.studio.newtrack	Log plays to database

Alternatives

For pull-based access to now-playing data, the Public API exposes the same metadata without configuring an endpoint. Use webhooks for push notifications and the API for on-demand requests.