Webhooks

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

Path: Station > Settings > Webhooks

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	Description
station.studio.newtrack	A new track starts playing in the studio
station.encoder.statuschange	An encoder connects, disconnects, or errors

Adding a Webhook

1. Navigate to Station > Settings > Webhooks
2. Click Add Webhook
3. Enter the destination URL
4. Select the trigger event
5. Click Save

Configuration Fields

Field	Description
URL	The endpoint that receives POST requests
Trigger	The event that activates the webhook
Enabled	Toggle to activate or deactivate
Secret	Optional shared secret for request signing

Payload Format

Webhooks send JSON data in the POST request body.

New Track Event

{
  "event": "station.studio.newtrack",
  "timestamp": "2026-01-26T14:30:00Z",
  "station": {
    "id": "sta_abc123",
    "name": "Radio Example"
  },
  "track": {
    "id": "med_xyz789",
    "title": "Hey Jude",
    "artist": "The Beatles",
    "album": "Past Masters",
    "duration": 431
  }
}

Encoder Status Change Event

{
  "event": "station.encoder.statuschange",
  "timestamp": "2026-01-26T14:30:00Z",
  "station": {
    "id": "sta_abc123",
    "name": "Radio Example"
  },
  "encoder": {
    "id": "enc_def456",
    "name": "Main Stream",
    "status": "connected",
    "previousStatus": "disconnected"
  }
}

Request Signing

When a secret is configured, xtra includes a signature header for verification.

Header	Description
X-Webhook-Signature	HMAC-SHA256 hash of the request body

Verify the signature by computing the HMAC-SHA256 of the raw request body using your secret and comparing it to the header value.

Testing Webhooks

Use webhook.site to test webhook delivery:

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

Retry Behavior

Scenario	Behavior
Success (2xx response)	Delivery complete
Server error (5xx)	Retry up to 3 times with exponential backoff
Client error (4xx)	No retry, check URL and configuration
Timeout (30 seconds)	Retry up to 3 times

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